search

Rust-for-Linux / linux

Adding support for the Rust language to the Linux kernel.
https://rust-for-linux.com
Other
3.98k stars 430 forks source link

Clean section header order, document it and implement a `checkpatch.pl` check #1116

Open y86-dev opened 1 month ago

y86-dev commented 1 month ago

We want to standardize the order in which we list section headers in rustdoc. The reason for this is that the API relevant sections should come first, in order to not miss them. The suggested ordering is:

The first four sections are part of the API surface of the documented item. # Invariants are listed as the last section, because they are implementation detail rather than belonging to the API. This should only be the standard for items that are not modules. For modules, we usually have custom sections.

Fix the ordering in existing code (for example there are some instances in rust/kernel/workqueue.rs), document the ordering under Documentation/rust/coding-guidelines.rst and create a checkpatch.pl check. Each of theses should be its own patch; depending on the size of the changes in existing code, you might want to split that up into multiple patches as well.

Please note that the checkpatch.pl maintainers will need to agree to the change.

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.

frazar commented 1 month ago

Based on the wording of the last paragraph, I believe this issue is missing the "good first issue" label.

y86-dev commented 1 month ago

I intentionally did not put the label on there yet: I wanted to know if someone objected to the proposal in the zulip, I plan to add the label tomorrow, if nobody shouts

kuku929 commented 1 month ago

hello, can I work on this?

y86-dev commented 1 month ago

sure, go ahead (or did @frazar also want to take a shot at this?)

frazar commented 1 month ago

Thank you, but I don't plan to work on this. @kuku929 you can go ahead!