Add API documentation front page styleguide

[jonathandturner]

This adds a proposal for the API documentation front page (the front matter you see when you first look at a crate's documentation). This is intended specifically for rust-lang crates, but works as suggested guidelines for any crate authors.

[BurntSushi]

Rendered.

[sfackler]

A couple newlines got chomped here.

[sfackler]

README or rustdoc?

[nagisa]

I always find myself copying the description from the crate-level introduction to README. Something that we could work on abstracting.

[alexcrichton]

I think @sfackler's comment here is actually an interesting one when taken more broadly as well. In terms of the "front page" of a crate, should we conventionally put more efforts into READMEs or crate documentation?

A README tends to actually be the first thing you read when hitting a crate (e.g. looking at the source on GitHub), and only afterwards might you go look at the documentation. That being said I'd personally prefer to put all documentation into the crate as it reduces duplication and it should "live with the code". Perhaps though discussion about this may be appropriate for this RFC?

[nagisa]

You mean front page of documentation as generated by rustdoc? “API” is a function or a set of functions exposed to other programmers and the acronym is in no way related to presentation.

[nagisa]

primary purpose, for most Rust developers, will be to produce any random number

That is a great misconception. It is very easy to incorrectly decide on a random number generator for pretty much all the use cases without taking in account the cryptosafety of the generator and the need for it. Even the trivial die-rolling games are flawed without a crypto-safe generator in some circumstances.

That being said, I do agree that discussion about generator’s crypto-safety should be elsewhere (such as the generators themselves)

[nagisa]

Lately I’ve begun to also include a snippet that may be copy-pasted into a Cargo.toml (reasons in next paragraph). I’d suggest including that into this recommendation as well.

I do so, because the first thing I check out about the crate is its documentation. Seeing something like

//! ```toml
//! [build-dependencies]
//! gcc = "0.3"
//! ```

saves me the effort of:

• remembering the crate name (e.g. crate is gcc, repository is gcc-rs; causes confusion);
• figuring out what the latest version is;
• what section I am supposed to put the dependency into;

The last point is esp. important when adding a dependency to a project which had no dependencies before, or adding the dependency in non-trivial ways (say with some features enabled/disabled) – I have trouble remembering how to do those things all the time.

---

Basically my first example becomes a Usage instead with step-by-step instructions on how to use a crate beginning with getting it into your cargo project.

[frewsxcv]

saves me the effort of:

• figuring out what the latest version is;

From what I've witnessed, It is very common for library maintainers to forget to bump this number in the documentation, which I think is a worse user-experience than just not mentioning it at all.

That said, when it is the correct version number, I do find the section helpful. So I'm pretty neutral on this.

[mdinger]

When someone links to the docs, there often isn't a link back to the repo or the crate which isn't really nice. This can be manually added but often isn't. It could be added as a convention.

Alternatively, maybe a shield could be added for the crate and repository or something. It seems like something which would probably be easy to include in rustdoc (not quite sure but it seems like it).

[nrc]

When someone links to the docs, there often isn't a link back to the repo or the crate which isn't really nice. This can be manually added but often isn't. It could be added as a convention.

If we make that a convention or shield, could we do the same for a link to crates.io, I also often want that from a docs page.

[mdinger]

That's actually what I meant by crate but yeah, that'd be cool.

[jbcden]

s/why the/why of the

[GuillaumeGomez]

About the README overlaps, IMO, it's normal. The only differences should be:

• Dependencies of the crate.
• How to build this crate.
• Links to CIs status.

These things shouldn't be in the doc and should remain in the README file.

[jbcden]

s/'rand'/rand

[jbcden]

I wonder if this should be a link. When mentioning the log crate above you make it a link. I don't think a link has been provided for rand yet despite multiple mentions.

[jbcden]

s/rand/rand or a link?

[jbcden]

s/demonstrated 5/demonstrated in 5

[Havvy]

Do these guidelines actually necessitate changing any crates to match the guidelines?

[matklad]

I also find it useful when a landing page of the API docs contains links to source code repository and the crates.iopackage.

Right now, for example, it is impossible to discover github repository of the log using only https://doc.rust-lang.org/log/log/index.html.

[frewsxcv]

I also find it useful when a landing page of the API docs contains links to source code repository and the crates.io package.

I also see the value in adding a link to the source repository from the API documentation. This is tangential, but couldn't this be done automatically by retrieving the repository value in 'Cargo.toml' and putting somewhere in the generated documentation?

[aturon]

Ping on this RFC -- what's the status?

[aturon]

cc @brson @rust-lang/libs

[jonathandturner]

@aturon - got distracted onto other things. I'll see if I can find the notes on what needed to be revised...

[aturon]

@jonathandturner Checking in again on this -- relevant to the libs team work. cc @dtolnay as well.

[dtolnay]

Hey @jonathandturner, could I get push access to your fork for the duration of this RFC? That way we can keep all the discussion in one PR.

[jonathandturner]

@dtolnay - invited! BTW, feel free to pull me into discussions on it. I'm glad someone's taking this and running with it 😄

[dtolnay]

I have updated the RFC to address the feedback so far and add my own experience. Rendered

• I clarified the purpose of the introduction using an approach that I have found helpful in writing to-the-point introductions in the past. I think this concrete advice will be more valuable than something hand-wavy and obvious like "the what and the why of the crate."
• I combined the capabilities and examples sections but with a note that examples may live under each capability or all together in an Examples section. In my experience neither of these approaches works well for every crate.
• I would like this RFC to clarify the relationship between the rustdoc front page and the project's readme. I made a list of some things that have traditionally gone in the readme but not the front page doc, and some projects that have readmes/doc of varying levels of similarity.
• I added lots of alternative ideas.
• I added lots of unresolved questions.

[QuietMisdreavus]

So, when talking with the docs team about it, we generally like what's going on here, but we're not entirely sure how to address the unresolved question of what's actually different between a crate's front matter and its README.

I'll just add my own experience here. Here's what I put in a README that doesn't necessarily go in the front matter, in addition to the items already listed:

• "How to add this library to your project" boilerplate. Each crate I have that's published, I have a little toml blurb and extern crate line in the README that shows how to add that crate to a rust project. I leave these out of the generated documentation, though, because in the context of "what does this library do" those lines are just noise.
• Description of the examples/ directory, or anything specific to the layout of the repository itself. I may link to the repository from the crate-root documentation, but I haven't actually said "In examples/tweet.rs you can see several of these methods being used" because I haven't wanted to create those links in a place that's likely to grow stale if I update the example code or the layout of that directory itself.

If I were to apply a generalization to these things and the things already listed in the RFC, I might consider "Things that apply solely or primarily to the source code or the layout of the repo belong in the README." The "how to use this" boilerplate would fall under an additional "background knowledge" provision, since I personally would consider that knowledge to be out of scope for the a specific library's documentation.

[aturon]

Bump on this -- can we drive to a resolution?

[steveklabnik]

I am going to re-read this and related RFCs soon; some of the other ones may change the way this RFC should work, especially things like #1990

[dtolnay]

I don't think I have bandwidth for this in the next 2 weeks before the impl period.

[steveklabnik]

@dtolnay is postponing maybe the right choice then?

[steveklabnik]

@rfcbot postpone

Given @dtolnay 's comment above, and that this would need revisions based on other non-accepted RFCs, I suggest we postpone this till next year.

[dtolnay]

@rfcbot fcp postpone

[steveklabnik]

@rfcbot fcp postpone

[rfcbot]

Team member @steveklabnik has proposed to postpone this. The next step is review by the rest of the tagged teams:

• @GuillaumeGomez
• @QuietMisdreavus
• @frewsxcv
• @jonathandturner
• @steveklabnik

No concerns currently listed.

Once these reviewers reach consensus, this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[steveklabnik]

Checking off @jonathandturner since he's not on the team anymore; should update @rfcbot !

[QuietMisdreavus]

@rfcbot reviewed

[frewsxcv]

@rfcbot reviewed

[aturon]

I'm going to go ahead and close this out as postponed, since the impl period has started. Thanks all!