diff mbox series

[12/13] rust: kernel: remove unneeded doclink targets

Message ID 20240117001549.169160-1-kernel@valentinobst.de
State New
Headers
Series rust: kernel: documentation improvements |

Commit Message

Valentin Obst Jan. 17, 2024, 12:15 a.m. UTC 
  Remove explicit targets for doclinks in cases where rustdoc can
determine the correct target by itself. The goal is to reduce verbosity
in the source code.

Signed-off-by: Valentin Obst <kernel@valentinobst.de>
---
 rust/kernel/workqueue.rs | 10 ----------
 1 file changed, 10 deletions(-)

Comments

Trevor Gross Jan. 18, 2024, 1:14 a.m. UTC | #1 
On Tue, Jan 16, 2024 at 7:16 PM Valentin Obst <kernel@valentinobst.de> wrote:
>
> Remove explicit targets for doclinks in cases where rustdoc can
> determine the correct target by itself. The goal is to reduce verbosity
> in the source code.
>
> Signed-off-by: Valentin Obst <kernel@valentinobst.de>
> ---
>  rust/kernel/workqueue.rs | 10 ----------
>  1 file changed, 10 deletions(-)

Perhaps "reduce verbosity" -> "reduce unneeded verbosity" in the commit message?

Reviewed-by: Trevor Gross <tmgross@umich.edu>
Trevor Gross Jan. 18, 2024, 1:21 a.m. UTC | #2 
On Tue, Jan 16, 2024 at 7:16 PM Valentin Obst <kernel@valentinobst.de> wrote:
>
> Remove explicit targets for doclinks in cases where rustdoc can
> determine the correct target by itself. The goal is to reduce verbosity
> in the source code.
>
> Signed-off-by: Valentin Obst <kernel@valentinobst.de>
> ---
>  rust/kernel/workqueue.rs | 10 ----------
>  1 file changed, 10 deletions(-)
>
> diff --git a/rust/kernel/workqueue.rs b/rust/kernel/workqueue.rs
> index aedf47f258bd..f63190b563d8 100644
> --- a/rust/kernel/workqueue.rs
> +++ b/rust/kernel/workqueue.rs
> @@ -426,13 +426,10 @@ pub unsafe fn raw_get(ptr: *const Self) -> *mut bindings::work_struct {
>  /// The [`OFFSET`] constant must be the offset of a field in `Self` of type [`Work<T, ID>`]. The
>  /// methods on this trait must have exactly the behavior that the definitions given below have.
>  ///
> -/// [`Work<T, ID>`]: Work
> [...]

Just for reference, this behavior is described at
https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html#valid-links:

> You can also refer to items with generic parameters like Vec<T>. The
> link will resolve as if you had written [`Vec<T>`](Vec)
diff mbox series

Patch

diff --git a/rust/kernel/workqueue.rs b/rust/kernel/workqueue.rs
index aedf47f258bd..f63190b563d8 100644
--- a/rust/kernel/workqueue.rs
+++ b/rust/kernel/workqueue.rs
@@ -426,13 +426,10 @@  pub unsafe fn raw_get(ptr: *const Self) -> *mut bindings::work_struct {
 /// The [`OFFSET`] constant must be the offset of a field in `Self` of type [`Work<T, ID>`]. The
 /// methods on this trait must have exactly the behavior that the definitions given below have.
 ///
-/// [`Work<T, ID>`]: Work
 /// [`impl_has_work!`]: crate::impl_has_work
 /// [`OFFSET`]: HasWork::OFFSET
 pub unsafe trait HasWork<T, const ID: u64 = 0> {
     /// The offset of the [`Work<T, ID>`] field.
-    ///
-    /// [`Work<T, ID>`]: Work
     const OFFSET: usize;
 
     /// Returns the offset of the [`Work<T, ID>`] field.
@@ -440,7 +437,6 @@  pub unsafe trait HasWork<T, const ID: u64 = 0> {
     /// This method exists because the [`OFFSET`] constant cannot be accessed if the type is not
     /// [`Sized`].
     ///
-    /// [`Work<T, ID>`]: Work
     /// [`OFFSET`]: HasWork::OFFSET
     #[inline]
     fn get_work_offset(&self) -> usize {
@@ -452,8 +448,6 @@  fn get_work_offset(&self) -> usize {
     /// # Safety
     ///
     /// The provided pointer must point at a valid struct of type `Self`.
-    ///
-    /// [`Work<T, ID>`]: Work
     #[inline]
     unsafe fn raw_get_work(ptr: *mut Self) -> *mut Work<T, ID> {
         // SAFETY: The caller promises that the pointer is valid.
@@ -465,8 +459,6 @@  unsafe fn raw_get_work(ptr: *mut Self) -> *mut Work<T, ID> {
     /// # Safety
     ///
     /// The pointer must point at a [`Work<T, ID>`] field in a struct of type `Self`.
-    ///
-    /// [`Work<T, ID>`]: Work
     #[inline]
     unsafe fn work_container_of(ptr: *mut Work<T, ID>) -> *mut Self
     where
@@ -495,8 +487,6 @@  unsafe fn work_container_of(ptr: *mut Work<T, ID>) -> *mut Self
 ///     impl HasWork<MyStruct, 17> for MyStruct { self.work_field }
 /// }
 /// ```
-///
-/// [`HasWork<T, ID>`]: HasWork
 #[macro_export]
 macro_rules! impl_has_work {
     ($(impl$(<$($implarg:ident),*>)?