Add references to RFCs defining good documentation practices

[cljoly]

In these RFCs, great details and example are given about the right way to do
documentation. I’m not sure if this is worth being detailed on
cheats.rs, but a link is a way as good as another to find these
documents.

In particular, these RFC are way more detailed than the Reference book.

See Rust-lang Contributing.md for a proof that RFC1574 is used for std.

[ralfbiedert]

I'm torn on this one. I think the essence of "how to write docs" should be part of the API guidelines, and that one should be / is linked.

However, right now the API Guidelines / Section 4 link to a mildly confusing RFC1687 thread, that backlinks to RFC 1574, from all of which you have to piece together that information yourself.

Until the API guidelines are fixed it might make sense to link the RFCs directly. I wouldn't link RFC0505 though, but just Appendix A of RFC1574 as you did, which already contains the full version. Also, as the RFC is somewhat opinionated and std-specific, I'd place that link in a "Idiomatic Rust / Documentation" (or maybe "More Cheats") section.

Any thoughts?

[cljoly]

I forgot the API Gudelines / Section 4. But after going back to this, I agree, it is less useful than RFC1574.

It could make sense to list some of the common headings:

• Examples
• Panics
• Errors
• Safety
• Aborts
• Undefined Behavior

I would definitely like to have such a list in a cheat sheet. When coding, it allows to make sure you didn’t forget to document anything important.

I could do a separate PR for this, if you wish.

[ralfbiedert]

I would definitely like to have such a list in a cheat sheet. When coding, it allows to make sure you didn’t forget to document anything important.

Two thoughts:

• From a developer perspective, would you want to find the documentation guidelines in isolation (on cheats.rs) to make sure you didn't forget anything? To me they are tied to the rest of the API Guidelines, and I want to make sure I follow the rest of these guides as well.

• Is the link to the API Guidelines (prominent) enough? Maybe we should either link to the guidelines more prominently; or even embed the checklist right here, at the risk of creating redundancy.

My concern boils down to: aren't documentation guidelines an "API design" concern? I totally agree C-CRATE-DOC is not good as it is, but once that is fixed, what's our relation to the rest of the API Guidelines?

[ralfbiedert]

Quick FYI, I changed "Idiomatic Rust" to now include "API Design", and also filed an issue about C-CRATE-DOC (rust-lang/api-guidelines#188).

[cljoly]

I have just added a commit to show what I would like to see on cheats.rs about headings in doc comments.
The new API and doc comments sections, however, are just an idea.

About your thoughts:

• With the headings in cheats.rs, I can check I have covered the main aspects. Even if it is tied to the rest of the API guidelines, having a few headings serves as a reminder and is unlikely to change that much very often.
• I’m afraid the link to API Guidelines is not prominent enough, but I don’t have any better idea… Maybe the API section could make the link more visible. I wouldn’t embed the checklist on cheats.rs: it would require quite a lot of work to maintain and the checklist might thus often be out of date. Plus, the checklist is already like a cheat-sheet of it’s own, I can’t see what cheats.rs could trim to make it shorter.

[cljoly]

About the merge conflict, I could do another PR with changes of 6e23df2

[ralfbiedert]

I like the new version much more where it's listed as part of the Idiomatic Rust table, thanks! I'll merge and make some fine adjustments to see how it looks.

Once the API Guidelines change I might rework this a bit more, but I'll try to keep the spirit of this PR alive. If you feel things regress over time, feel free to open an Issue / PR.

[cljoly]

Awesome!