Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add references to RFCs defining good documentation practices #25

Merged
merged 2 commits into from Jan 23, 2019

Conversation

cljoly
Copy link

@cljoly cljoly commented Jan 19, 2019

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.

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
https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#writing-documentation
for a proof that RFC1574 is used for std.
@ralfbiedert
Copy link
Owner

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
Copy link
Author

cljoly commented Jan 19, 2019

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
Copy link
Owner

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
Copy link
Owner

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).

We create a section about doc comments and API, it’s not just tooling.
@cljoly
Copy link
Author

cljoly commented Jan 21, 2019

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
Copy link
Author

cljoly commented Jan 21, 2019

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

@ralfbiedert
Copy link
Owner

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
Copy link
Author

cljoly commented Jan 23, 2019

Awesome!

@ralfbiedert ralfbiedert merged commit 6e23df2 into ralfbiedert:master Jan 23, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants