Conversation
Jarkko Sakkinen
jarkko
Edited 2 months ago
Speaking of recent events at LKML concerning #Rust and #kernel, and also what I've said in some threads, the key element for reaching tolerance is #documentation.
This does not mean that bad behavior is acceptable but great documentation is best means to be preventive of such events ever occurring. Right now Rust kernel documentation almost does not exist.
What is an appropriate granularity for documentation? It is the level where an experienced kernel maintainer who has *never* used Rust can still understand your kernel patch.
That is the ideal. Obviously not always reached but underlines how bad state Rust documentation is ATM. I blame for most of this #Google and #Microsoft, not the developers. They are two private companies who spend vasta amounts of money for Rust kernel work. And they should know what I said already.
This does not mean that bad behavior is acceptable but great documentation is best means to be preventive of such events ever occurring. Right now Rust kernel documentation almost does not exist.
What is an appropriate granularity for documentation? It is the level where an experienced kernel maintainer who has *never* used Rust can still understand your kernel patch.
That is the ideal. Obviously not always reached but underlines how bad state Rust documentation is ATM. I blame for most of this #Google and #Microsoft, not the developers. They are two private companies who spend vasta amounts of money for Rust kernel work. And they should know what I said already.
1
4
4
@jarkko I hate to say it, but I think you are setting an impossible standard here. Is there any subsystem in the kernel, written in any language, that is so well documented that a developer unfamiliar with the implementation language could understand a patch to it?
The kernel's documentation is ... not great ... and it seems to me that the Rust folks are trying to do a little better.
The kernel's documentation is ... not great ... and it seems to me that the Rust folks are trying to do a little better.
1
0
7
@corbet It could be improved by being more integral part of the review process. NCC Groups article series ”Rustproofing” provides a good example of how to explain Rust kernel internals. I see it just as a process improvement, not something that I would expect to be fixed in fast phase. Starting from simple example there is rustdoc/kdoc and rst/md. I could not find any guidance which convention should be used for documenting an exported symbol.
1
0
0
@corbet it is also a money question. We must enforce big companies like Microsoft to use a portion of their Rust budget to make it happen if they are unwilling otherwise. It is also in the long run best for Linux Rust governance. Ie great and well documented features.
1
0
0
@corbet Despite maybe a different viewpoint I say my views with the hopes that Rust integration, spread and reach will all improve 🙂 Personally Ive found existing kernel documentation, yes, messy but also full of details that I actually need. Ive used Rust in userland professionally since early 2022 so not exactly a ”denialist”. I do get its benefits especially in the uapi layer.
0
0
0