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

docs: rust: fix formatting for kernel::block::mq::Request #1111

Open
wants to merge 1 commit into
base: rust-next
Choose a base branch
from

Conversation

frazar
Copy link

@frazar frazar commented 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: #1108

Suggested-by: Miguel Ojeda [email protected]

@frazar
Copy link
Author

frazar commented Sep 1, 2024

If possible, I would like to receive a review of this patch. In particular, on the way I configured the Makefiles to pass the --document-private-items argument to rustdoc.

@@ -162,7 +162,7 @@ in the kernel:
a section called ``# Examples``.

- Rust items (functions, types, constants...) must be linked appropriately
(``rustdoc`` will create a link automatically).
by wrapping them with square brackets (e.g. ``[`Foo::bar()`]``).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is nice adding the explanation, but I think we should also keep the original sentence.

This should be an independent commit, too.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you! I have removed these changes from the commit. Should I submit them as a second PR?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're welcome! I think they would be 3 independent PRs, since they are mostly independent (i.e. the cleanup, the docs improvement and the proposal to document private items; the latter likely being an RFC). In any case, please note that each change that you want to submit will need to end up in the mailing list -- we don't really use PRs anymore, except for early reviews like this one. Thanks!

Makefile Outdated Show resolved Hide resolved
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
Copy link
Member

ojeda commented Sep 3, 2024

@ojeda ojeda force-pushed the rust-next branch 3 times, most recently from c9b5ce6 to ce1c54f Compare October 9, 2024 22:37
@ojeda ojeda force-pushed the rust-next branch 3 times, most recently from 9ee7197 to 6ce162a Compare October 15, 2024 21:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

Successfully merging this pull request may close these issues.

Clean kernel::block::mq::Request docs to render properly
2 participants