[RFC] Documentation and comment fixes in kernel crate

[vobst]

Hi all!

To get familiar with the Rust kernel infrastructure I read through the existing in-tree code. Along the way I fixed some trivial things in comments and documentation, as well as making some small improvements by adding doclinks. This PR only looks at the kernel crate.

• Nothing here touches actual code.
• I tested the changes by recompiling the documentation (adding --document-private-items), running make rusttest to (hopefully) run the doctests, and running make rustfmtcheck to check the formatting. (Also recompiled and ran the the kernel and smaple modules, but this actually should not matter.)

Since this would be my first upstream contribution I'd appreciate some upfront review before I submit to the mailing list. In particular:

• are the proposed changes OK?
• is the splitting into individual commits appropriate?
• are the commit messages OK?
• should I make one or two patch sets?

Thanks!

[charmitro]

* are the commit messages OK?

Two notes in the case you send this upstream via mailing list.

1. The commits in github are from an unknown profile. You can fix it by modifying your git config.
2. You should add Signed-off-by: ... in the commits.

In general, if you fix your git config, signing the commits can be done automatically via git commit -s.

[bjorn3]

The commits in github are from an unknown profile.

If you actually look at the commits you will see that the author name and email are set correctly. They probably didn't add the email they used to their github account, so github doesn't show the associated github account as author.

[vobst]

rusttest only runs the few #[test]s we have. For doctests, you want to use KUnit (make sure you have CONFIG_RUST_KERNEL_DOCTESTS=y). Please see https://docs.kernel.org/next/rust/general-information.html#testing.

Ah, ok, I was already suspecting that this wasn't the right thing. Will do that.

I think you did commits by area in some cases, which is fine, but for trivial-enough things that apply to more places, you can do a single commit for everything. For instance rust: init: fix multiple typos in documentation could be rust: kernel: fix multiple typos in documentation and, given its "generic" title, it could take typos from some of the other commits perhaps (e.g. the one from rust: workqueue: fix trivial typo in docs of __enqueue).

Sure, I'll squash those trivial typofixes.

Also, in rust: workqueue: add doclinks, you also remove others. So the title should probably be different (e.g. "improve"?). Or you can keep the title and do the removals in another commit (and, again, ideally applied to more than just workqueue).

Afaik this commit should only add doc links. The removals are cases where it is not necessary to give the explicit link target as rustdoc can figure it out itself. They could go into their own commit though.

Also, you can use Markdown in commit messages if you wish (in the Rust subsystem we typically do, but different people in the kernel use different styles).

Nice, I prefer Markdown as well.

[vobst]

@charmitro @bjorn3 Yes, I did not add that email address to my GH account.

[vobst]

I'll include the changelog between this RFC and the v1 I submit to the mailing list below to aid the reviewers that already gave feedback here:

• squashed trivial typo fixes into a single commit; In particular I squashed

  11ee461ad rust: workqueue: fix trivial typo in docs of __enqueue
  e3f961290 rust: spinlock: fix typo in 'unlock' SAFETY comment
  ec6a49930 rust: str: fix trivial typo in bytes_written docs
  b0a2c7a70 rust: ioctl: fix indefinite articles in doc comments
  fecc9b554 rust: init: fix multiple typos in documentation
  c95a3d882 rust: allocator: fix indentation in comment

• now using Markdown to highlight code fragments in commit messages
• dropped d3cb9b509 rust: remove 'rust' annotation on code blocks in docs
• dropped a2f0cea40 rust: remove doclinks in regular comments in favor of a separate patch set that also touches the coding guidelines
• remove changes to long form of refcount and include statistics in commit message (rust: unify spelling of refcount in docs)
• rust: workqueue: add doclinks is now rust: kernel: add doclinks and adds doclinks across the kernel crate; I also moved the parts that remove unneeded explicit doc link targets and introduce new links with the "code" html tag into their own commits
• rust: mark code elements in comments with backticks now includes the ioctl()
• rust: kernel: add doclinks now includes Sized in the workqueue module
• Added "Signed-of-by" to all commits.
• There is one new commit rust: locked_by: shorten doclink preview. It changes two link previews from super::type name to type name.

This time I also properly ran the doctests.

Edit: the v1 tree is here