From nobody Wed Dec 17 09:49:59 2025 Received: from mout.kundenserver.de (mout.kundenserver.de [212.227.126.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 965A61DA2C; Tue, 16 Jan 2024 23:11:35 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=212.227.126.133 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1705446697; cv=none; b=gOpulVKLC9e+wl0plkDFr2CnoZMCulnvR8v+Fa9ULL/NmCv1gd5mA1zyvspYRyVY8WmjWjIA3ERiVWwgwF5VisgKbSvlIqzMVk9xnwT+5UJu8fmt1Jh6IN1ucP9BcF+ENIQUQyBC/T5BC1hKi8uzA1VFpp27DM9XQJhdzqHFjPI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1705446697; c=relaxed/simple; bh=MGssKXKFpJmMR/MBNNgGqevsBNhT1o85Az3TxIhlZAM=; h=Received:From:To:Cc:Subject:Date:Message-ID:X-Mailer:In-Reply-To: References:MIME-Version:Content-Transfer-Encoding:X-Provags-ID: X-Spam-Flag:UI-OutboundReport; b=Nw9WMs2vAMRh//pqLFcRY4rGUe5S/rrgNPZ8W4JY2BSlIIQwVUiOM6jV3oKp0/TKEKK2uesUn2bQdVU5/qOky50cK7N27P3SecB3FbdA6hMUjWVpvUFdh+N8SFtIbgpRVHqW/SeZmHK0LMnVjTaRUsh6tgyEqhOsRP5K3XvAvec= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=valentinobst.de; spf=pass smtp.mailfrom=valentinobst.de; arc=none smtp.client-ip=212.227.126.133 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=valentinobst.de Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=valentinobst.de Received: from localhost.localdomain ([217.245.156.100]) by mrelayeu.kundenserver.de (mreue011 [213.165.67.97]) with ESMTPSA (Nemesis) id 1MWAjC-1reqJ90vEo-00XaJ8; Wed, 17 Jan 2024 00:11:21 +0100 From: Valentin Obst To: Miguel Ojeda , Alex Gaynor , Wedson Almeida Filho Cc: Boqun Feng , Gary Guo , =?UTF-8?q?Bj=C3=B6rn=20Roy=20Baron?= , Benno Lossin , Andreas Hindborg , Alice Ryhl , rust-for-linux@vger.kernel.org, linux-kernel@vger.kernel.org, Valentin Obst Subject: [PATCH 11/13] rust: kernel: add doclinks with html tags Date: Wed, 17 Jan 2024 00:11:18 +0100 Message-ID: <20240116231118.168882-1-kernel@valentinobst.de> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20240116160141.165951-1-kernel@valentinobst.de> References: <20240116160141.165951-1-kernel@valentinobst.de> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Provags-ID: V03:K1:7HDVl5ICHcjvu8IpxbaBi4RT96IEY2WzS7HNpagrRLMKzjKGrrp HNDQsDnObQM5UfrcYAKFPKwKCa5nfWzXvBIhcQwMJ9ILV9sF0MGkg7zqBWx5GBG/DFKg4br w6eGrh4MfDydzwKak28EhlPwcRYRAEDzgEpaXfBiZvigBZhg7xTY6oby3zkYbHY8xe5FyRR EZsHCecWfOGzI74G8BReA== X-Spam-Flag: NO UI-OutboundReport: notjunk:1;M01:P0:5/VYKVZVSV4=;5l1Im1o2v77FVLbOqnVkHhisSp0 k7AS8oXGuUvRGhQthNOkF/ZLN3ir5LJulRiGMeaQCTZ8BdgQ6/YkrwDFPI4w+e1AWm9BOaata OwdzxKXhi6TEGb6SXsDir/NhL+ssLJIGSCMeDs0Cy1JrZKM+Qm66e1TeY9I5wggc4oHl2fYJa cFCv87mieIxot1SuDI3up88/WIJ8ZMGdHF5VTMTR2uydvg3Nh4zyKpdEyCMW5CSInX6gGUB+Q 0owTLgdWQlMzEzG7XN1S+fSLi3fBSalsGUE68KI3+KAfs566BsmTMHbF0sq4vscw9to+P3oG/ tHyydKRGmstfuTZqjYX9hPSTBb7BZUiXJsIQEnRtnLB4wDob8znUlmqwAaMYxT2d9osf+Dvdm rolqsi7ke/u/R6L5Ni8OC4HPwMoqAgqOgHs6rzxPIUS7drdvwqQRCPUPYoNodytJxSuBWPYzE Tvet71iNl/dLwjI6KmFwlyU6uAJeGy+49vGe9Zyf8tm9EXn2ixIGjpoTtx7vRiS9v32AZuY2d f/c2lCYKh5BqYnWCO+Hv2v3jQiuTaqGidN2N9kFlV4f3zwsttmUVgb+VNkttlMUnCfIwg+3ky gdRVX69LvhRifswlpnEQHDxbF+dKnlp3XefUiCXRDUkJgWkog8W/yAE1NPRrTVstsGDyo3zNH 9eeik+58hxfoJSf7shMMg2+rtDNoum2MQvMYWKHq8b3oEGuP2XNOLgMDUyu1+e+USqehxJBeT dHigE4RXSqu63/wzgmF1N6GY7poSDkVloE0wyzT3W7EkcnP/glVszmjoG0nBAGtK52wfBnuu2 omZd/jRq5030D5HlJxGpHiv3MHJIG5kurtqQZq2QuE2idwkoTJ7noDkiHxDtD/D4vYz11ub+h Gz4TCR8aGjt+yTw9Mq4WffazeSk724w8ufBM= Content-Type: text/plain; charset="utf-8" Add doclinks to existing documentation. Use html 'code' tags to add links to items that cannot be linked with the normal syntax. The use of html tags is a tradeoff between the readability of the documentation's source code and the ergonomics of the generated content. Signed-off-by: Valentin Obst --- rust/kernel/str.rs | 7 ++++--- rust/kernel/sync/arc.rs | 24 +++++++++++++----------- rust/kernel/workqueue.rs | 10 +++++----- 3 files changed, 22 insertions(+), 19 deletions(-) diff --git a/rust/kernel/str.rs b/rust/kernel/str.rs index fec5c4314758..f95fd2ba19fb 100644 --- a/rust/kernel/str.rs +++ b/rust/kernel/str.rs @@ -14,7 +14,8 @@ =20 /// Byte string without UTF-8 validity guarantee. /// -/// `BStr` is simply an alias to `[u8]`, but has a more evident semantical= meaning. +/// `BStr` is simply an alias to [[u8]], but has a more evide= nt +/// semantical meaning. pub type BStr =3D [u8]; =20 /// Creates a new [`BStr`] from a string literal. @@ -106,7 +107,7 @@ pub unsafe fn from_char_ptr<'a>(ptr: *const core::ffi::= c_char) -> &'a Self { unsafe { Self::from_bytes_with_nul_unchecked(bytes) } } =20 - /// Creates a [`CStr`] from a `[u8]`. + /// Creates a [`CStr`] from a [[u8]]. /// /// The provided slice must be `NUL`-terminated, does not contain any /// interior `NUL` bytes. @@ -130,7 +131,7 @@ pub const fn from_bytes_with_nul(bytes: &[u8]) -> Resul= t<&Self, CStrConvertError Ok(unsafe { Self::from_bytes_with_nul_unchecked(bytes) }) } =20 - /// Creates a [`CStr`] from a `[u8]` without performing any additional + /// Creates a [`CStr`] from a [[u8]] without performing a= ny additional /// checks. /// /// # Safety diff --git a/rust/kernel/sync/arc.rs b/rust/kernel/sync/arc.rs index 936bc549a082..5fcd4b0fd84b 100644 --- a/rust/kernel/sync/arc.rs +++ b/rust/kernel/sync/arc.rs @@ -368,10 +368,10 @@ fn from(item: Pin>) -> Self { /// to use just `&T`, which we can trivially get from an [`Arc`] instan= ce. /// /// However, when one may need to increment the refcount, it is preferable= to use an `ArcBorrow` -/// over `&Arc` because the latter results in a double-indirection: a p= ointer (shared reference) -/// to a pointer ([`Arc`]) to the object (`T`). An [`ArcBorrow`] elimin= ates this double -/// indirection while still allowing one to increment the refcount and get= ting an [`Arc`] when/if -/// needed. +/// over &[`Arc`] because the latter results in a double-i= ndirection: a pointer +/// (shared reference) to a pointer ([`Arc`]) to the object (`T`). An [= `ArcBorrow`] eliminates +/// this double indirection while still allowing one to increment the refc= ount and getting an +/// [`Arc`] when/if needed. /// /// # Invariants /// @@ -489,8 +489,8 @@ fn deref(&self) -> &Self::Target { /// # Examples /// /// In the following example, we make changes to the inner object before t= urning it into an -/// `Arc` object (after which point, it cannot be mutated directly).= Note that `x.into()` -/// cannot fail. +/// [Arc]\ object (after which point, it cannot be mut= ated directly). +/// Note that `x.into()` cannot fail. /// /// ``` /// use kernel::sync::{Arc, UniqueArc}; @@ -512,8 +512,9 @@ fn deref(&self) -> &Self::Target { /// /// In the following example we first allocate memory for a refcounted `Ex= ample` but we don't /// initialise it on allocation. We do initialise it later with a call to = [`UniqueArc::write`], -/// followed by a conversion to `Arc`. This is particularly usefu= l when allocation happens -/// in one context (e.g., sleepable) and initialisation in another (e.g., = atomic): +/// followed by a conversion to [Arc]\. This is par= ticularly useful when +/// allocation happens in one context (e.g., sleepable) and initialisation= in another +/// (e.g., atomic): /// /// ``` /// use kernel::sync::{Arc, UniqueArc}; @@ -532,8 +533,8 @@ fn deref(&self) -> &Self::Target { /// ``` /// /// In the last example below, the caller gets a pinned instance of `Examp= le` while converting to -/// `Arc`; this is useful in scenarios where one needs a pinned r= eference during -/// initialisation, for example, when initialising fields that are wrapped= in locks. +/// [Arc]\; this is useful in scenarios where one n= eeds a pinned reference +/// during initialisation, for example, when initialising fields that are = wrapped in locks. /// /// ``` /// use kernel::sync::{Arc, UniqueArc}; @@ -582,7 +583,8 @@ pub fn try_new_uninit() -> Result>, AllocError> { } =20 impl UniqueArc> { - /// Converts a `UniqueArc>` into a `UniqueArc` by wr= iting a value into it. + /// Converts a UniqueArc<[`MaybeUninit`]> into a `Uniq= ueArc` + /// by writing a value into it. pub fn write(mut self, value: T) -> UniqueArc { self.deref_mut().write(value); // SAFETY: We just wrote the value to be initialized. diff --git a/rust/kernel/workqueue.rs b/rust/kernel/workqueue.rs index ed3af3491b47..aedf47f258bd 100644 --- a/rust/kernel/workqueue.rs +++ b/rust/kernel/workqueue.rs @@ -294,9 +294,9 @@ unsafe fn __enqueue(self, queue_work_on: F) -> Self:= :EnqueueOutput =20 /// Defines the method that should be called directly when a work item is = executed. /// -/// This trait is implemented by `Pin>` and [`Arc`], and is main= ly intended to be -/// implemented for smart pointer types. For your own structs, you would i= mplement [`WorkItem`] -/// instead. The [`run`] method on this trait will usually just perform th= e appropriate +/// This trait is implemented by [Pin]<[`Box`]> and [`Arc<= T>`], and is mainly +/// intended to be implemented for smart pointer types. For your own struc= ts, you would implement +/// [`WorkItem`] instead. The [`run`] method on this trait will usually ju= st perform the appropriate /// `container_of` translation and then call into the [`run`][WorkItem::ru= n] method from the /// [`WorkItem`] trait. /// @@ -325,8 +325,8 @@ pub unsafe trait WorkItemPointer: RawWor= kItem { /// /// This trait is used when the `work_struct` field is defined using the [= `Work`] helper. pub trait WorkItem { - /// The pointer type that this struct is wrapped in. This will typical= ly be `Arc` or - /// `Pin>`. + /// The pointer type that this struct is wrapped in. This will typical= ly be + /// [Arc]\ or [Pin]<[Box]\>. type Pointer: WorkItemPointer; =20 /// The method that should be called when this work item is executed. --=20 2.43.0