Add missing docs, enforce missing-docs and doc compiler_builtins

[ojeda]

Signed-off-by: Miguel Ojeda ojeda@kernel.org

[ojeda]

I know it looks like a lot, but I'd appreciate if anyone could take a look at all the new comments in particular -- most of the rest is just style changes etc.

The idea here is to try to to showcase how good rustdoc-docs can look like, in terms of how easy it is to write the content, link to Rust items via intra-doc links, how easy it is to read in the HTML form (with the navigation etc.), etc. The point is to show that we can improve the situation over the current kernel documentation (where one typically needs to navigate header files, implementation files, search the Documentation/ folder, perhaps even use an external cross-referencer, etc.).

Long-term, the idea is to also link C functions and types automatically. From an early discussion with the rustdoc team they seemed to like a proposal I discussed with them, hopefully I can write the RFC soon.

[alex]

FWIW I'm reviewing all PRs after I finish work, so there's a delay for me on weekdays :-)

…

On Thu, Feb 25, 2021 at 9:31 AM Miguel Ojeda ***@***.***> wrote: I know it looks like a lot, but I'd appreciate if anyone could take a look at all the new comments in particular -- most of the rest is just style changes etc. The idea here is to try to to showcase how good rustdoc-docs can look like, in terms of how easy it is to write the content, link to Rust items via intra-doc links, how easy it is to read in the HTML form (with the navigation etc.), etc. The point is to show that we can improve the situation over the current kernel documentation (where one typically needs to navigate header files, implementation files, search the Documentation/ folder, perhaps even use an external cross-referencer, etc.). Long-term, the idea is to also link C functions and types automatically. From an early discussion with the rustdoc team they seemed to like a proposal I discussed with them, hopefully I can write the RFC soon. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#95 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAAGBGS4365DCSFGIL63M3TAZNLRANCNFSM4YGSNOZQ> .

-- All that is necessary for evil to succeed is for good people to do nothing.

[ojeda]

@alex No worries, take your time, this one is a bit of a mess to review :-)

[ojeda]

Ah, I forgot to include a "comment style guide" to explain how I was harmonizing things (e.g. "use intra-doc links wherever possible", "max 80 width for comments", "end sentences with a period", "no contractions", etc.).

Anyway, I will do it in another PR, enough for this one ;-)