On Thu, Apr 6, 2023 at 4:15 PM Daniel Vetter <daniel@xxxxxxxx> wrote: > > Documentation: > > In drm we try to document all the interfaces that drivers use with formal > docs. Yes there's some areas that are not great for historical reasons, > but for new stuff and new wrappers we're really trying: > > - This helps in telling internal (even across .c files or in rust across > modules within a crate) from stuff drivers access. Sure you have static > in C or pub in rust, but that doesn't tell you whether it's public all > the way to drivers. I think you may be talking about the value high-level docs here, but just in case, visibility in Rust is flexible enough to expose (or not) APIs to those that you need. In other words, it does tell you (and enforces!) whether it is public all the way to drivers. There is also the possibility of even more fancy visibility, but so far we just needed `pub(crate)`. `rustdoc` also shows/hides things as needed, thus the generated docs for the crate should only show what is usable by others. Then there is the `kernel` crate split, too. > - ideally docs have a short intro section that explains the main concepts > and links to the main data structures and functions. Just to give > readers a good starting point to explore. Agreed, this is typically done in Rust in the top-level doc comments (module or crate). For the Rust side of the kernel, we are definitely trying to emphasize the quality of the docs, including compile- and runtime-tested examples. Regarding linking, `rustdoc` already generates a listing with the contents of each crate/module even if there is no other docs. So as long as the short descriptions of the items are good, it may be fairly readable already, e.g. see https://rust-for-linux.github.io/docs/rust/kernel/sync/index.html for an example in our old `rust` branch. But, of course, you can add extra docs at that level too when there are many things or is unclear what should be used. Also note that, sometimes, the docs we write are in the type, rather than the module, e.g. see the nice examples Wedson wrote for `RBTree`: https://rust-for-linux.github.io/docs/rust/kernel/rbtree/struct.RBTree.html. > - Linking all the things, so that readers can connect the different parts. > This is really important in C where e.g. get/put() or any such function > pairs all needed to be linked together. With rust I'm hoping that > rustdoc liberally sprinkles links already and we don't have to do this > as much. If you mean within doc comments, it does! :) It is called "intra-doc links". Basically, you just write something in-between square brackets, and it is able to create the link to the right thing (in most cases, otherwise you can help it more), e.g. /// Returns a new [`Foo`]. And, of course, for the rest of things that aren't inside comments, it automatically provides links etc. There has been work on `rustdoc` on getting "Jump to Definition" and similar features to work on the source view, too. > - Short explainers for parameters. For rust this also means type > parameters, for those even simplified examples of how drivers are > supposed to use them would help a lot in reading docs & understanding > concepts. For parameters, we are not forcing to write explanations for every parameter (as in providing a list), but rather writing what is actually useful to know (referring to the parameters as needed). So it depends on a case-by-case. In any case, in general is clearer what parameters are compared to C, due to the stronger typing. Of course, if one uses integers everywhere, it is as confusing as C. But if one has a type, it is easier to tell, plus one may jump with a click into the explanation of that type etc. Regarding examples, 100% agreed. And not only that, the examples are enforced to be kept up to date by compiling and running them via KUnit (not yet submitted for mainline, but we have been enforcing it for our old `rust` branch for a long time). > - Ideally links from the rust to the sphinx side to linke relevant > chapters together. Often the bigger explanations are in .rst files with > DOT graphs (kms has a bunch I've added) or similar, and it doesn't make > that much sense to duplicate all that on the rust side I guess. But it > needs to be discoverable. Definitely. One next step is having easy-to-write links to the rST docs. For this, a couple years ago I talked with the `rustdoc` maintainers about having a "External references map file" feature, so that we can link rST documents from the Rust docs, including generated C docs too. For instance, ideally we would be able to use the square brackets around a C type and have it work: /// Exposes the kernel’s [`struct wait_queue_head`] as a condition variable. Regarding the bigger explanations: we are trying to keep most of the docs close to the Rust code where it makes sense, as module-level/crate-level docs, rather than as rST docs. This has several benefits, like keeping them closer to the code, the linking features, having them organized equally as the code, no need to know whether there is a doc somewhere or not (e.g. if it is, it is near the code), examples are compiled, etc. Of course, sometimes longer-form docs and other documents may not make sense as part of any code in particular, or may be shared across C and Rust, etc., and there it may more sense to use `Documentation/` files instead. But, in general, the idea is that, compared to C, most of the docs go into the code. To give an idea of the difference: so far, in our old `rust` branch, we only needed a few documents in `Documentation/` (e.g. the Quick Start guide etc.), and everything else went into the code itself. Cheers, Miguel
