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.

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

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

You're welcome -- please go ahead!

frazar added a commit to frazar/linux that referenced this issue Sep 1, 2024
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 <[email protected]>
frazar added a commit to frazar/linux that referenced this issue Sep 1, 2024
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 <[email protected]>
Suggested-by: Miguel Ojeda <[email protected]>
frazar added a commit to frazar/linux that referenced this issue Sep 1, 2024
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 <[email protected]>
Suggested-by: Miguel Ojeda <[email protected]>
frazar added a commit to frazar/linux that referenced this issue Sep 1, 2024
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 <[email protected]>
Suggested-by: Miguel Ojeda <[email protected]>
frazar added a commit to frazar/linux that referenced this issue Sep 1, 2024
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 <[email protected]>
Suggested-by: Miguel Ojeda <[email protected]>
frazar added a commit to frazar/linux that referenced this issue Sep 1, 2024
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 <[email protected]>
Suggested-by: Miguel Ojeda <[email protected]>
@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
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 <[email protected]>
Closes: Rust-for-Linux#1108
Signed-off-by: Francesco Zardi <[email protected]>
Acked-by: Andreas Hindborg <[email protected]>
Fixes: 3253aba ("rust: block: introduce `kernel::block::mq` module")
Link: https://lore.kernel.org/r/[email protected]
[ Added an extra intra-doc link. Took the chance to add some periods
  for consistency. Reworded slightly. - Miguel ]
Signed-off-by: Miguel Ojeda <[email protected]>
alistair23 pushed a commit to alistair23/linux that referenced this issue Nov 12, 2024
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 <[email protected]>
Closes: Rust-for-Linux#1108
Signed-off-by: Francesco Zardi <[email protected]>
Acked-by: Andreas Hindborg <[email protected]>
Fixes: 3253aba ("rust: block: introduce `kernel::block::mq` module")
Link: https://lore.kernel.org/r/[email protected]
[ Added an extra intra-doc link. Took the chance to add some periods
  for consistency. Reworded slightly. - Miguel ]
Signed-off-by: Miguel Ojeda <[email protected]>
johnny-mnemonic pushed a commit to linux-ia64/linux-stable-rc that referenced this issue Dec 2, 2024
[ Upstream commit 28e8483 ]

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 <[email protected]>
Closes: Rust-for-Linux/linux#1108
Signed-off-by: Francesco Zardi <[email protected]>
Acked-by: Andreas Hindborg <[email protected]>
Fixes: 3253aba ("rust: block: introduce `kernel::block::mq` module")
Link: https://lore.kernel.org/r/[email protected]
[ Added an extra intra-doc link. Took the chance to add some periods
  for consistency. Reworded slightly. - Miguel ]
Signed-off-by: Miguel Ojeda <[email protected]>
Signed-off-by: Sasha Levin <[email protected]>
johnny-mnemonic pushed a commit to linux-ia64/linux-stable-rc that referenced this issue Dec 2, 2024
[ Upstream commit 28e8483 ]

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 <[email protected]>
Closes: Rust-for-Linux/linux#1108
Signed-off-by: Francesco Zardi <[email protected]>
Acked-by: Andreas Hindborg <[email protected]>
Fixes: 3253aba ("rust: block: introduce `kernel::block::mq` module")
Link: https://lore.kernel.org/r/[email protected]
[ Added an extra intra-doc link. Took the chance to add some periods
  for consistency. Reworded slightly. - Miguel ]
Signed-off-by: Miguel Ojeda <[email protected]>
Signed-off-by: Sasha Levin <[email protected]>
johnny-mnemonic pushed a commit to linux-ia64/linux-stable-rc that referenced this issue Dec 2, 2024
[ Upstream commit 28e8483 ]

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 <[email protected]>
Closes: Rust-for-Linux/linux#1108
Signed-off-by: Francesco Zardi <[email protected]>
Acked-by: Andreas Hindborg <[email protected]>
Fixes: 3253aba ("rust: block: introduce `kernel::block::mq` module")
Link: https://lore.kernel.org/r/[email protected]
[ Added an extra intra-doc link. Took the chance to add some periods
  for consistency. Reworded slightly. - Miguel ]
Signed-off-by: Miguel Ojeda <[email protected]>
Signed-off-by: Sasha Levin <[email protected]>
johnny-mnemonic pushed a commit to linux-ia64/linux-stable-rc that referenced this issue Dec 2, 2024
[ Upstream commit 28e8483 ]

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 <[email protected]>
Closes: Rust-for-Linux/linux#1108
Signed-off-by: Francesco Zardi <[email protected]>
Acked-by: Andreas Hindborg <[email protected]>
Fixes: 3253aba ("rust: block: introduce `kernel::block::mq` module")
Link: https://lore.kernel.org/r/[email protected]
[ Added an extra intra-doc link. Took the chance to add some periods
  for consistency. Reworded slightly. - Miguel ]
Signed-off-by: Miguel Ojeda <[email protected]>
Signed-off-by: Sasha Levin <[email protected]>
johnny-mnemonic pushed a commit to linux-ia64/linux-stable-rc that referenced this issue Dec 4, 2024
[ Upstream commit 28e8483 ]

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 <[email protected]>
Closes: Rust-for-Linux/linux#1108
Signed-off-by: Francesco Zardi <[email protected]>
Acked-by: Andreas Hindborg <[email protected]>
Fixes: 3253aba ("rust: block: introduce `kernel::block::mq` module")
Link: https://lore.kernel.org/r/[email protected]
[ Added an extra intra-doc link. Took the chance to add some periods
  for consistency. Reworded slightly. - Miguel ]
Signed-off-by: Miguel Ojeda <[email protected]>
Signed-off-by: Sasha Levin <[email protected]>
johnny-mnemonic pushed a commit to linux-ia64/linux-stable-rc that referenced this issue Dec 4, 2024
[ Upstream commit 28e8483 ]

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 <[email protected]>
Closes: Rust-for-Linux/linux#1108
Signed-off-by: Francesco Zardi <[email protected]>
Acked-by: Andreas Hindborg <[email protected]>
Fixes: 3253aba ("rust: block: introduce `kernel::block::mq` module")
Link: https://lore.kernel.org/r/[email protected]
[ Added an extra intra-doc link. Took the chance to add some periods
  for consistency. Reworded slightly. - Miguel ]
Signed-off-by: Miguel Ojeda <[email protected]>
Signed-off-by: Sasha Levin <[email protected]>
johnny-mnemonic pushed a commit to linux-ia64/linux-stable-rc that referenced this issue Dec 4, 2024
[ Upstream commit 28e8483 ]

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 <[email protected]>
Closes: Rust-for-Linux/linux#1108
Signed-off-by: Francesco Zardi <[email protected]>
Acked-by: Andreas Hindborg <[email protected]>
Fixes: 3253aba ("rust: block: introduce `kernel::block::mq` module")
Link: https://lore.kernel.org/r/[email protected]
[ Added an extra intra-doc link. Took the chance to add some periods
  for consistency. Reworded slightly. - Miguel ]
Signed-off-by: Miguel Ojeda <[email protected]>
Signed-off-by: Sasha Levin <[email protected]>
johnny-mnemonic pushed a commit to linux-ia64/linux-stable-rc that referenced this issue Dec 4, 2024
[ Upstream commit 28e8483 ]

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 <[email protected]>
Closes: Rust-for-Linux/linux#1108
Signed-off-by: Francesco Zardi <[email protected]>
Acked-by: Andreas Hindborg <[email protected]>
Fixes: 3253aba ("rust: block: introduce `kernel::block::mq` module")
Link: https://lore.kernel.org/r/[email protected]
[ Added an extra intra-doc link. Took the chance to add some periods
  for consistency. Reworded slightly. - Miguel ]
Signed-off-by: Miguel Ojeda <[email protected]>
Signed-off-by: Sasha Levin <[email protected]>
johnny-mnemonic pushed a commit to linux-ia64/linux-stable-rc that referenced this issue Dec 5, 2024
[ Upstream commit 28e8483 ]

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 <[email protected]>
Closes: Rust-for-Linux/linux#1108
Signed-off-by: Francesco Zardi <[email protected]>
Acked-by: Andreas Hindborg <[email protected]>
Fixes: 3253aba ("rust: block: introduce `kernel::block::mq` module")
Link: https://lore.kernel.org/r/[email protected]
[ Added an extra intra-doc link. Took the chance to add some periods
  for consistency. Reworded slightly. - Miguel ]
Signed-off-by: Miguel Ojeda <[email protected]>
Signed-off-by: Sasha Levin <[email protected]>
johnny-mnemonic pushed a commit to linux-ia64/linux-stable-rc that referenced this issue Dec 5, 2024
[ Upstream commit 28e8483 ]

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 <[email protected]>
Closes: Rust-for-Linux/linux#1108
Signed-off-by: Francesco Zardi <[email protected]>
Acked-by: Andreas Hindborg <[email protected]>
Fixes: 3253aba ("rust: block: introduce `kernel::block::mq` module")
Link: https://lore.kernel.org/r/[email protected]
[ Added an extra intra-doc link. Took the chance to add some periods
  for consistency. Reworded slightly. - Miguel ]
Signed-off-by: Miguel Ojeda <[email protected]>
Signed-off-by: Sasha Levin <[email protected]>
Whissi pushed a commit to Whissi/linux-stable that referenced this issue Dec 5, 2024
[ Upstream commit 28e8483 ]

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 <[email protected]>
Closes: Rust-for-Linux/linux#1108
Signed-off-by: Francesco Zardi <[email protected]>
Acked-by: Andreas Hindborg <[email protected]>
Fixes: 3253aba ("rust: block: introduce `kernel::block::mq` module")
Link: https://lore.kernel.org/r/[email protected]
[ Added an extra intra-doc link. Took the chance to add some periods
  for consistency. Reworded slightly. - Miguel ]
Signed-off-by: Miguel Ojeda <[email protected]>
Signed-off-by: Sasha Levin <[email protected]>
woodsts pushed a commit to woodsts/linux-stable that referenced this issue Dec 5, 2024
[ Upstream commit 28e8483 ]

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 <[email protected]>
Closes: Rust-for-Linux/linux#1108
Signed-off-by: Francesco Zardi <[email protected]>
Acked-by: Andreas Hindborg <[email protected]>
Fixes: 3253aba ("rust: block: introduce `kernel::block::mq` module")
Link: https://lore.kernel.org/r/[email protected]
[ Added an extra intra-doc link. Took the chance to add some periods
  for consistency. Reworded slightly. - Miguel ]
Signed-off-by: Miguel Ojeda <[email protected]>
Signed-off-by: Sasha Levin <[email protected]>
johnny-mnemonic pushed a commit to linux-ia64/linux-stable-rc that referenced this issue Dec 6, 2024
[ Upstream commit 28e8483 ]

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 <[email protected]>
Closes: Rust-for-Linux/linux#1108
Signed-off-by: Francesco Zardi <[email protected]>
Acked-by: Andreas Hindborg <[email protected]>
Fixes: 3253aba ("rust: block: introduce `kernel::block::mq` module")
Link: https://lore.kernel.org/r/[email protected]
[ Added an extra intra-doc link. Took the chance to add some periods
  for consistency. Reworded slightly. - Miguel ]
Signed-off-by: Miguel Ojeda <[email protected]>
Signed-off-by: Sasha Levin <[email protected]>
kongwoojin pushed a commit to kongwoojin/linux-kernel that referenced this issue Dec 13, 2024
[ Upstream commit 28e848386b92645f93b9f2fdba5882c3ca7fb3e2 ]

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 <[email protected]>
Closes: Rust-for-Linux/linux#1108
Signed-off-by: Francesco Zardi <[email protected]>
Acked-by: Andreas Hindborg <[email protected]>
Fixes: 3253aba ("rust: block: introduce `kernel::block::mq` module")
Link: https://lore.kernel.org/r/[email protected]
[ Added an extra intra-doc link. Took the chance to add some periods
  for consistency. Reworded slightly. - Miguel ]
Signed-off-by: Miguel Ojeda <[email protected]>
Signed-off-by: Sasha Levin <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
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
Development

Successfully merging a pull request may close this issue.

2 participants