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.

Sign up for GitHub

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

Jump to bottom

Add API documentation front page styleguide #1687

Closed
wants to merge 26 commits into from
Closed

Add API documentation front page styleguide #1687

Changes from 1 commit
Commits
Show all changes
26 commits
Select commit Hold shift click to select a range
c43e66a
Add API documentation front page styleguide
Jul 25, 2016
5c84df4
Update formatting (thanks vim)
Jul 25, 2016
09b551e
More formatting updates
Jul 25, 2016
d94849b
Cleans up links and formatting.
peschkaj Aug 19, 2016
b4ff67a
Merge pull request #1 from peschkaj/front_page_styleguide
Aug 19, 2016
74c84e9
How we teach front page documentation
dtolnay May 7, 2017
14b424d
Clean up trailing whitespace
dtolnay May 7, 2017
5e7544d
Mention readme in the summary
dtolnay May 8, 2017
4754fdd
Tie this to 2017 roadmap
dtolnay May 8, 2017
f278e48
Fold examples under each capability
dtolnay May 8, 2017
0192c10
Brainstorm some alternatives and open questions
dtolnay May 8, 2017
565d2c1
Where to put license boilerplate
dtolnay May 8, 2017
87f3972
Where to explain getting help
dtolnay May 8, 2017
ec3e74f
Rewrap consistently
dtolnay May 8, 2017
8793929
Factor links out of the paragraphs
dtolnay May 8, 2017
6d6c1a8
Rethink the purpose of the introduction
dtolnay May 8, 2017
3e5662b
Multi crate guidance
dtolnay May 8, 2017
7b0bd87
Example budget
dtolnay May 8, 2017
feb4972
Migration notes
dtolnay May 8, 2017
0cb8cca
Crystalize the purpose of the first example
dtolnay May 8, 2017
8b54517
Preserve backticks in the original
dtolnay May 8, 2017
8636aeb
This example prints to stdout as a side effect
dtolnay May 8, 2017
509a323
Wording
dtolnay May 8, 2017
708f120
Smaller headings in the quoted text
dtolnay May 8, 2017
7348e61
Readme unresolved question
dtolnay May 8, 2017
4cce1e2
Where to put capability examples
dtolnay May 8, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Wording
  • Loading branch information
@dtolnay
dtolnay committed May 8, 2017
commit 509a32309ba1bec384af47890e03dfadda5fad93
14 changes: 7 additions & 7 deletions text/0000-api-doc-frontpage-styleguide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 10,7 @@ This time we focus on the format and style of the "front page" of documentation
as generated by rustdoc. The goal of this RFC is to outline a clear presentation
style for crate documentation that is helpful to new users of a crate. We also
clarify the relationship between the rustdoc front page and the project's
readme. These are the guidelines we'll be using for the rust-lang crates, but
readme. These are the guidelines we will be using for the rust-lang crates, but
are also meant to help guide community crate authors.

[RFC 1574]: https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md
Expand Down Expand Up @@ -139,11 139,11 @@ and how to use them. For example, in a crate about random numbers, you may have
sections about: generating random numbers, fitting numbers to statistical
distributions, use in cryptography, thread-local random numbers, and so on.

It's helpful to introduce and give a clear description for each capability
It is helpful to introduce and give a clear description for each capability
separately to help your readers understand each concept individually before they
begin to combine capabilities.

Here's a good example from the `rand` crate:
Here is a good example from the `rand` crate:

> ## Thread-local RNG
>
Expand Down Expand Up @@ -181,10 181,10 @@ More complex source examples should be included as a separate program in the
`examples` directory. Be wary of putting large examples in your doc where users
will have to read past the code to get the beginning of your API documentation.

You should also avoid examples that require understanding of external crates
unless it's absolutely necessary. As a hypothetical example - your logging crate
should not require the user to have experience with [Diesel]. It's okay to leave
these capabilities as an exercise left to the reader.
You should avoid examples that require understanding of external crates unless
it is necessary. As a hypothetical example, your logging crate should not
require the user to have experience with [Diesel]. It is okay to leave these
integrations for the reader to put together themselves.

[Diesel]: https://diesel.rs/

Expand Down