[PATCH] rust: block: fix formatting in GenDisk doc

[PATCH] rust: block: fix formatting in GenDisk doc

[Yutaro Ohno]

Align bullet points and improve indentation in the `Invariants` section
of the `GenDisk` struct documentation for better readability.

Fixes: 3253aba3408a ("rust: block: introduce `kernel::block::mq` module")
Signed-off-by: Yutaro Ohno <yutaro.ono.418@gmail.com>
---
 rust/kernel/block/mq/gen_disk.rs | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/rust/kernel/block/mq/gen_disk.rs b/rust/kernel/block/mq/gen_disk.rs
index 708125dce96a..c6df153ebb88 100644
--- a/rust/kernel/block/mq/gen_disk.rs
+++ b/rust/kernel/block/mq/gen_disk.rs
@@ -174,9 +174,9 @@ pub fn build<T: Operations>(
 ///
 /// # Invariants
 ///
-///  - `gendisk` must always point to an initialized and valid `struct gendisk`.
-///  - `gendisk` was added to the VFS through a call to
-///     `bindings::device_add_disk`.
+/// - `gendisk` must always point to an initialized and valid `struct gendisk`.
+/// - `gendisk` was added to the VFS through a call to
+///   `bindings::device_add_disk`.
 pub struct GenDisk<T: Operations> {
     _tagset: Arc<TagSet<T>>,
     gendisk: *mut bindings::gendisk,
-- 
2.47.0

Re: [PATCH] rust: block: fix formatting in GenDisk doc

[Boqun Feng]

On Thu, Oct 24, 2024 at 12:54:59AM +0900, Yutaro Ohno wrote:
> Align bullet points and improve indentation in the `Invariants` section
> of the `GenDisk` struct documentation for better readability.
> 
> Fixes: 3253aba3408a ("rust: block: introduce `kernel::block::mq` module")
> Signed-off-by: Yutaro Ohno <yutaro.ono.418@gmail.com>

This looks good to me, but not sure we need a "Fixes:" tag, Miguel?

Reviewed-by: Boqun Feng <boqun.feng@gmail.com>

Regards,
Boqun

> ---
>  rust/kernel/block/mq/gen_disk.rs | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/rust/kernel/block/mq/gen_disk.rs b/rust/kernel/block/mq/gen_disk.rs
> index 708125dce96a..c6df153ebb88 100644
> --- a/rust/kernel/block/mq/gen_disk.rs
> +++ b/rust/kernel/block/mq/gen_disk.rs
> @@ -174,9 +174,9 @@ pub fn build<T: Operations>(
>  ///
>  /// # Invariants
>  ///
> -///  - `gendisk` must always point to an initialized and valid `struct gendisk`.
> -///  - `gendisk` was added to the VFS through a call to
> -///     `bindings::device_add_disk`.
> +/// - `gendisk` must always point to an initialized and valid `struct gendisk`.
> +/// - `gendisk` was added to the VFS through a call to
> +///   `bindings::device_add_disk`.
>  pub struct GenDisk<T: Operations> {
>      _tagset: Arc<TagSet<T>>,
>      gendisk: *mut bindings::gendisk,
> -- 
> 2.47.0
> 

Re: [PATCH] rust: block: fix formatting in GenDisk doc

[Miguel Ojeda]

On Wed, Oct 23, 2024 at 6:00 PM Boqun Feng <boqun.feng@gmail.com> wrote:
>
> This looks good to me, but not sure we need a "Fixes:" tag, Miguel?

I think it is fine either way (it depends on who you ask).

Personally, I don't mind having it or not, but sometimes I may
nevertheless take trivial fixes like this one through `rust-next`
instead of `rust-fixes`.

Thanks!

Cheers,
Miguel

Re: [PATCH] rust: block: fix formatting in GenDisk doc

[Miguel Ojeda]

On Wed, Oct 23, 2024 at 5:55 PM Yutaro Ohno <yutaro.ono.418@gmail.com> wrote:
>
> Align bullet points and improve indentation in the `Invariants` section
> of the `GenDisk` struct documentation for better readability.
>
> Fixes: 3253aba3408a ("rust: block: introduce `kernel::block::mq` module")
> Signed-off-by: Yutaro Ohno <yutaro.ono.418@gmail.com>

Andreas: happy to apply this through `rust-next` if needed.

It would be good to have some automated checking on this, just like
`doc_lazy_continuation` does, so I opened:

    https://github.com/rust-lang/rust-clippy/issues/13601

Cheers,
Miguel

Re: [PATCH] rust: block: fix formatting in GenDisk doc

[Miguel Ojeda]

On Thu, Oct 24, 2024 at 4:02 PM Miguel Ojeda
<miguel.ojeda.sandonis@gmail.com> wrote:
>
> Andreas: happy to apply this through `rust-next` if needed.

Ping -- do you want me to take it?

Thanks!

Cheers,
Miguel

Re: [PATCH] rust: block: fix formatting in GenDisk doc

[Andreas Hindborg]

"Miguel Ojeda" <miguel.ojeda.sandonis@gmail.com> writes:

> On Thu, Oct 24, 2024 at 4:02 PM Miguel Ojeda
> <miguel.ojeda.sandonis@gmail.com> wrote:
>>
>> Andreas: happy to apply this through `rust-next` if needed.
>
> Ping -- do you want me to take it?

Sure, go ahead 👍


Best regards,
Andreas Hindborg

Re: [PATCH] rust: block: fix formatting in GenDisk doc

[Andreas Hindborg]

"Yutaro Ohno" <yutaro.ono.418@gmail.com> writes:

> Align bullet points and improve indentation in the `Invariants` section
> of the `GenDisk` struct documentation for better readability.
>
> Fixes: 3253aba3408a ("rust: block: introduce `kernel::block::mq` module")
> Signed-off-by: Yutaro Ohno <yutaro.ono.418@gmail.com>
> ---
>  rust/kernel/block/mq/gen_disk.rs | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/rust/kernel/block/mq/gen_disk.rs b/rust/kernel/block/mq/gen_disk.rs
> index 708125dce96a..c6df153ebb88 100644
> --- a/rust/kernel/block/mq/gen_disk.rs
> +++ b/rust/kernel/block/mq/gen_disk.rs
> @@ -174,9 +174,9 @@ pub fn build<T: Operations>(
>  ///
>  /// # Invariants
>  ///
> -///  - `gendisk` must always point to an initialized and valid `struct gendisk`.
> -///  - `gendisk` was added to the VFS through a call to
> -///     `bindings::device_add_disk`.
> +/// - `gendisk` must always point to an initialized and valid `struct gendisk`.
> +/// - `gendisk` was added to the VFS through a call to
> +///   `bindings::device_add_disk`.
>  pub struct GenDisk<T: Operations> {
>      _tagset: Arc<TagSet<T>>,
>      gendisk: *mut bindings::gendisk,


Acked-by: Andreas Hindborg <a.hindborg@kernel.org>


Best regards,
Andreas Hindborg

Re: [PATCH] rust: block: fix formatting in GenDisk doc

[Miguel Ojeda]

On Wed, Oct 23, 2024 at 5:55 PM Yutaro Ohno <yutaro.ono.418@gmail.com> wrote:
>
> Align bullet points and improve indentation in the `Invariants` section
> of the `GenDisk` struct documentation for better readability.
>
> Fixes: 3253aba3408a ("rust: block: introduce `kernel::block::mq` module")
> Signed-off-by: Yutaro Ohno <yutaro.ono.418@gmail.com>

Applied to `rust-next` -- thanks everyone!

    [ Yutaro is also working on implementing the lint we suggested to catch
      this sort of issue in upstream Rust:

        https://github.com/rust-lang/rust-clippy/issues/13601
        https://github.com/rust-lang/rust-clippy/pull/13711

      Thanks a lot! - Miguel ]

Since it doesn't affect the rendered output as far as I can see and it
is not really urgent, I have put it in -next. However, I kept the
Fixes tag -- if https://github.com/rust-lang/rust-clippy/pull/13711
gets merged and we start using it, it may be an actual fix that could
need to be backported eventually, so it doesn't hurt to keep it
around, and if it gets autoselected, that is fine too.

Cheers,
Miguel