Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clean kernel::block::mq::Request docs to render properly #1108

Closed
ojeda opened this issue Aug 31, 2024 · 2 comments · May be fixed by #1111
Closed

Clean kernel::block::mq::Request docs to render properly #1108

ojeda opened this issue Aug 31, 2024 · 2 comments · May be fixed by #1111
Labels
• docs Related to `Documentation/rust/`, `samples/`, generated docs, doctests, typos... easy Expected to be an easy issue to resolve. good first issue Good for newcomers

Comments

@ojeda
Copy link
Member

ojeda commented Aug 31, 2024

There are several documentation rendering issues in rust/kernel/block/mq/request.rs. For instance, there is an ordered list not rendering as such in -- clean it up so that it is rendered properly. There is also some inline code missing Markdown quotes nearby -- clean it up too. There are also some references to types that could be intra-doc links and/or are missing Markdown quotes.

This requires submitting a proper patch to the LKML and the Rust for Linux mailing list. Please recall to test your changes (including generating the documentation if changed, running the Rust doctests if changed, etc.), to use a proper title for the commit, to sign your commit under the Developer's Certificate of Origin and to add a Suggested-by: tag and a Link: tag to this issue. Please see https://rust-for-linux.com/contributing for details.

Please take this issue only if you are new to the kernel development process and you would like to use it as a test to submit your first patch to the kernel. Please do not take it if you do not plan to make other contributions to the kernel.
@ojeda ojeda added • docs Related to `Documentation/rust/`, `samples/`, generated docs, doctests, typos... good first issue Good for newcomers labels Aug 31, 2024
@frazar
Copy link

frazar commented Sep 1, 2024

Hi! Thanks for the very clear write-up. I would like to work on this issue.

@ojeda
Copy link
Member Author

ojeda commented Sep 1, 2024 •
edited
Loading

You're welcome -- please go ahead!

frazar added a commit to frazar/linux that referenced this issue Sep 1, 2024
@frazar
docs: rust: fix formatting for kernel::block::mq::Request
61dfcf3 
Fix several issues with rustdoc formatting for the
`kernel::block::mq::Request` module, in particular:

- An ordered list not rendering correctly.

- Code snippets formatted as regular text.

- References to types missing intra-doc links.

Additionally, to ensure that intra-doc links are rendered for private
types, add the `--document-private-items` flag to all rustdoc
invocations.

Finally, update the Rust coding guidelines to mention the syntax for
intra-doc links.

Closes: Rust-for-Linux#1108

Signed-off-by: Francesco Zardi <frazar0@hotmail.it>
frazar added a commit to frazar/linux that referenced this issue Sep 1, 2024
@frazar
docs: rust: fix formatting for kernel::block::mq::Request
273eeb7 
Fix several issues with rustdoc formatting for the
`kernel::block::mq::Request` module, in particular:

- An ordered list not rendering correctly.

- Code snippets formatted as regular text.

- References to types missing intra-doc links.

Additionally, to ensure that intra-doc links are rendered for private
types, add the `--document-private-items` flag to all rustdoc
invocations.

Finally, update the Rust coding guidelines to mention the syntax for
intra-doc links.

Closes: Rust-for-Linux#1108

Signed-off-by: Francesco Zardi <frazar0@hotmail.it>
Suggested-by: Miguel Ojeda <ojeda@kernel.org>
@frazar frazar mentioned this issue Sep 1, 2024
Open
frazar added a commit to frazar/linux that referenced this issue Sep 1, 2024
@frazar
docs: rust: fix formatting for kernel::block::mq::Request
f227cf9 
Fix several issues with rustdoc formatting for the
`kernel::block::mq::Request` module, in particular:

- An ordered list not rendering correctly.

- Code snippets formatted as regular text.

- References to types missing intra-doc links.

Additionally, to ensure that intra-doc links are rendered for private
types, add the `--document-private-items` flag to all rustdoc
invocations.

Finally, update the Rust coding guidelines to mention the syntax for
intra-doc links.

Closes: Rust-for-Linux#1108

Signed-off-by: Francesco Zardi <frazar0@hotmail.it>
Suggested-by: Miguel Ojeda <ojeda@kernel.org>
frazar added a commit to frazar/linux that referenced this issue Sep 1, 2024
@frazar
docs: rust: fix formatting for kernel::block::mq::Request
2e15daf 
Fix several issues with rustdoc formatting for the
`kernel::block::mq::Request` module, in particular:

- An ordered list not rendering correctly.

- Code snippets formatted as regular text.

- References to types missing intra-doc links.

Additionally, to ensure that intra-doc links are rendered for private
types, add the `--document-private-items` flag to all rustdoc
invocations.

Finally, update the Rust coding guidelines to mention the syntax for
intra-doc links.

Closes: Rust-for-Linux#1108

Signed-off-by: Francesco Zardi <frazar00@gmail.com>
Suggested-by: Miguel Ojeda <ojeda@kernel.org>
frazar added a commit to frazar/linux that referenced this issue Sep 1, 2024
@frazar
docs: rust: fix formatting for kernel::block::mq::Request
c6cd6a7 
Fix several issues with rustdoc formatting for the
`kernel::block::mq::Request` module, in particular:

- An ordered list not rendering correctly.

- Code snippets formatted as regular text.

- References to types missing intra-doc links.

Closes: Rust-for-Linux#1108

Signed-off-by: Francesco Zardi <frazar00@gmail.com>
Suggested-by: Miguel Ojeda <ojeda@kernel.org>
frazar added a commit to frazar/linux that referenced this issue Sep 1, 2024
@frazar
docs: rust: fix formatting for kernel::block::mq::Request
a9e86a2 
Fix several issues with rustdoc formatting for the
`kernel::block::mq::Request` module, in particular:

- An ordered list not rendering correctly.

- Code snippets formatted as regular text.

- References to types missing intra-doc links.

Closes: Rust-for-Linux#1108

Signed-off-by: Francesco Zardi <frazar00@gmail.com>
Suggested-by: Miguel Ojeda <ojeda@kernel.org>
@ojeda ojeda added the easy Expected to be an easy issue to resolve. label Oct 3, 2024
@ojeda ojeda closed this as completed in 28e8483 Oct 22, 2024
alistair23 pushed a commit to alistair23/linux that referenced this issue Nov 11, 2024
@frazar @alistair23
rust: block: fix formatting of kernel::block::mq::request module
eee9a79 
Fix several issues with rustdoc formatting for the
`kernel::block::mq::Request` module, in particular:

  - An ordered list not rendering correctly, fixed by using numbers
    prefixes instead of letters.

  - Code snippets formatted as regular text, fixed by wrapping the
    code with `back-ticks`.

  - References to types missing intra-doc links, fixed by wrapping the
    types with [square brackets].

Reported-by: Miguel Ojeda <ojeda@kernel.org>
Closes: Rust-for-Linux#1108
Signed-off-by: Francesco Zardi <frazar00@gmail.com>
Acked-by: Andreas Hindborg <a.hindborg@kernel.org>
Fixes: 3253aba ("rust: block: introduce `kernel::block::mq` module")
Link: https://lore.kernel.org/r/20240903173027.16732-3-frazar00@gmail.com
[ Added an extra intra-doc link. Took the chance to add some periods
  for consistency. Reworded slightly. - Miguel ]
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
• docs Related to `Documentation/rust/`, `samples/`, generated docs, doctests, typos... easy Expected to be an easy issue to resolve. good first issue Good for newcomers
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

docs: rust: fix formatting for kernel::block::mq::Request frazar/linux
2 participants
@frazar @ojeda