search

Rust-for-Linux / linux

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

Clean code documentation section names and implement a `checkpatch.pl` check for it #1110

Open ojeda opened 2 weeks ago

ojeda commented 2 weeks ago

We prefer plurals when writing code documentation sections: # Examples, # Invariants, # Guarantees and # Panics, so that it is consistent and so that one can add more examples without having to change the section name.

At the time of writing, there are a few instances that should be cleaned up. In another patch, a checkpatch.pl cheek should be added to avoid adding more cases.

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.

paddymills commented 1 week ago

Never written perl before, but I'll give this one a try.

Is it enough to consider all plurals to be words that end in 's'?

ojeda commented 1 week ago

I would probably just do it case-by-case, i.e. catch the wrong singulars that we know about, such as # Example, so that we avoid false positives.

paddymills commented 1 week ago

I put a message in zulip regarding this.

Basically, the checkpatch.pl kernel patch for this is being held up and noted as possibly an "overly trivial addition."

So, I am wondering if there is anything I should do different? Would adding more stylistic checks to checkpatch.pl help (if there are some to be found) or would that not be a good idea? Is there another tool that would be a better fit for these checks?