On Thu, Apr 6, 2023 at 5:45 PM Daniel Vetter daniel@ffwll.ch wrote:
Yeah this all looks great and very hyperlinked.
I think the only nit I have is that for types with two or more type variables (like the rbtree) what each of them should represent in the top intro. I can guess it's <Key, Value> and not the other way round, but confirmation takes quite a bit of scrolling to check with the function types.
Yeah, that is fair. Personally I prefer more descriptive names when there are several or they have a special/asymmetric role.
Otherwise I think perfect api docs.
Glad you like it!
Just a quick comment on this, that's the same we do on the C side. Most overview chapters are actually DOC: sections pulled in from the code.
What I meant here is that for big overview stuff (like for modesetting how the display pipe structures tie together as an example: https://dri.freedesktop.org/docs/drm/gpu/drm-kms.html#overview) it doesn't make sense to duplicate that in rustdoc once more.
Yeah, definitely, if it is already somewhere else for C, we shouldn't duplicate it (that is what I meant by the "shared across C and Rust" exception).
Maybe drm is the exception, but if you look at our .rst files we also have most of our docs in the code:
https://cgit.freedesktop.org/drm/drm/tree/Documentation/gpu/drm-kms-helpers....
The rst files just provide the scaffolding because C dosn't have crates/modules hierarchy that would do this for you automatically.
Sorry, I was talking in general in the kernel. That `drm-kms-helpers.rst` looks great.
From a quick grep, I think you are indeed one of the big users of `DOC: `, which indeed map closely to what you would do in Rust without the scaffolding need.
So I think you will like writing docs in Rust :)
Cheers, Miguel