Add rustdoc doc #66267
Merged
Add rustdoc doc #66267
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
GuillaumeGomez
force-pushed
the
add-rustdoc-doc
branch
2 times, most recently
from
0543358
to
8e41089
Compare
kinnison
reviewed
Nov 10, 2019
Comment on lines
3
to
6
| This chapter intends to explain how to not only write documentation but also on | ||
| how to write **good** ones. But something to keep in mind when writing | ||
| documentation: you write as much for others as for you so it's important to be | ||
| clear! The more the better. If an item is public, then it should be documented. |
There was a problem hiding this comment.
Multiline suggestions don't work, but I'd suggest:
This chapter covers not only how to write documentation but specifically
how to write **good** documentation. Something to keep in mind when
writing documentation is that your audience is not just yourself but others
who simply don't have the context you do. It is important to be as clear
as you can, and as complete as possible. As a rule of thumb, the more
documentation you write for your crate, the better. If an item is public
then it should be documented.|
|
||
| ## Basic structure | ||
|
|
||
| If possible, each item's documentation should try to follow this structure: |
There was a problem hiding this comment.
Suggested change
| If possible, each item's documentation should try to follow this structure: | |
| It is recommended that each item's documentation follows this basic structure: |
Comment on lines
22
to
24
| Pretty simple but important to follow. The code example is really important: | ||
| it might help your users to have a better understanding of what an item is | ||
| used for and/or how to use it. |
There was a problem hiding this comment.
I think it's risky to describe documentation as 'simple' to produce. Perhaps:
This basic structure should be straightforward to follow when writing your
documentation and, while you might think that a code example is trivial,
the examples are really important because they can help your users to
understand what an item is, how it is used, and for what purpose it exists.| used for and/or how to use it. | ||
|
|
||
| Let's see an example coming from the [standard library] by taking a look at the | ||
| [env::args] function: |
There was a problem hiding this comment.
Suggested change
| [env::args] function: | |
| [`std::env::args()`][env::args] function: |
Comment on lines
67
to
68
| The documentation is using the [commonmark markdown specification]. You might be | ||
| interested into taking a look at their website to see what's possible to do! |
There was a problem hiding this comment.
Here I think it's important to make it clear that rustdoc uses commonmark, and if possible some of the text about taking a look should try and link to the requisite part of the commonmark site. I also dislike the ! 😄
|
|
||
| Here is the list of the lints provided by `rustdoc`: | ||
|
|
||
| ## intra_doc_link_resolution_failure |
There was a problem hiding this comment.
Should we label this one "nightly only" ?
There was a problem hiding this comment.
Also should we say this is warn-by-default?
GuillaumeGomez
force-pushed
the
add-rustdoc-doc
branch
from
8e41089
to
a362924
Compare
|
Updated. |
|
The job Click to expand the log.I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact |
ehuss
reviewed
Nov 10, 2019
Comment on lines
+90
to
+91
| This lint is **allowed by default**. It detects documentation tests when they | ||
| are on a private item. For example: |
There was a problem hiding this comment.
Maybe this could have a brief comment explaining why someone might want to use it? From what I understand, private doc tests are tested, it's just that they do not have access to private items, so its usefulness is limited, is that correct?
My initial reading, I was thinking maybe private doc tests were not tested or something.
There was a problem hiding this comment.
This is not where we should give this explanation from my point of view.
kinnison
reviewed
Nov 10, 2019
| writing documentation is that your audience is not just yourself but others | ||
| who simply don't have the context you do. It is important to be as clear | ||
| as you can, and as complete as possible. As a rule of thumb, the more | ||
| documentation you write for your crate, the better. If an item is public |
There was a problem hiding this comment.
Suggested change
| documentation you write for your crate, the better. If an item is public | |
| documentation you write for your crate the better. If an item is public |
Looks like I left a spurious comma in before
| how to write **good** documentation. Something to keep in mind when | ||
| writing documentation is that your audience is not just yourself but others | ||
| who simply don't have the context you do. It is important to be as clear | ||
| as you can, and as complete as possible. As a rule of thumb, the more |
There was a problem hiding this comment.
Suggested change
| as you can, and as complete as possible. As a rule of thumb, the more | |
| as you can, and as complete as possible. As a rule of thumb: the more |
GuillaumeGomez
force-pushed
the
add-rustdoc-doc
branch
from
a362924
to
528b059
Compare
kinnison
approved these changes
Nov 11, 2019
|
Then let's get it in! @bors: r=kinnison rollup |
|
📌 Commit 528b059 has been approved by |
bors
added
the
S-waiting-on-bors
JohnTitor
added a commit
to JohnTitor/rust
that referenced
this pull request
Nov 12, 2019
…innison Add rustdoc doc r? @kinnison
bors
added a commit
that referenced
this pull request
Nov 12, 2019
Rollup of 11 pull requests Successful merges: - #65965 (Clean up librustc_typeck error_codes file) - #66230 (remove vestigial comments referring to defunct numeric trait hierarchy) - #66241 (bump openssl version) - #66257 (Drop long-section-names linker workaround for windows-gnu) - #66263 (make the error message more readable) - #66267 (Add rustdoc doc) - #66276 (Move lock into CodeStats) - #66278 (Fix error message about exported symbols from proc-macro crates) - #66280 (Fix HashSet::union performance) - #66299 (support issue = "none" in unstable attributes ) - #66309 (Tiny cleanup to size assertions) Failed merges: r? @ghost
Centril
added a commit
to Centril/rust
that referenced
this pull request
Mar 23, 2020
…vel-doc, r=Dylan-DPC Add lint when no doc is present at the crate-level Follow-up of rust-lang#66267. r? @kinnison
Centril
added a commit
to Centril/rust
that referenced
this pull request
Mar 23, 2020
…vel-doc, r=Dylan-DPC Add lint when no doc is present at the crate-level Follow-up of rust-lang#66267. r? @kinnison
bors
added a commit
to rust-lang-ci/rust
that referenced
this pull request
Mar 28, 2020
…l-doc, r=Dylan-DPC Add lint when no doc is present at the crate-level Follow-up of rust-lang#66267. r? @kinnison
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
r? @kinnison