On Thu, Feb 12, 2026 at 11:11 AM Boris Brezillon <[email protected]> wrote: > > Don't know what the doc rules are in rust, but for this sort of generic > layer, maybe we should provide extensive docs around objects, fields > and public functions. I see that most struct fields are documented, but > not the struct themselves. the enum doesn't seem to be documented, and > some of the public functions are not either. And that's all my fault, > because I gave you this raw piece of code without much doc (you added a > lot already). Just saying that, maybe now that things have settled > down, is a good time to add proper doc where it's missing.
Yeah, documentation is definitely welcome, and will be rendered for all crates in the future. We configure the compiler to require documentation for public items, and while it is not enforced for private ones, it is definitely wanted and expected unless unreasonable (e.g. too trivial or onerous). Examples are also encouraged. We generally try to be strict within the `kernel` crate, but we don't want to make things too hard either. It is a balance. Subsystems should decide on how strict they need/want to be on things like docs for private items. Some subsystems define further guidelines/rules, e.g. like Nova: https://docs.kernel.org/gpu/nova/guidelines.html A few related notes at (I am writing a "coding guidelines list" to go along that document with simple, short notes I have been accumulating over the months, and that may also be useful to give to AI review tooling): https://docs.kernel.org/rust/coding-guidelines.html#code-documentation I hope that helps. Cheers, Miguel
