Revamp missing documentation linting #6798
Closed
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
Add some more cases for warning about missing documentation, and also add a test to make sure it doesn't die in the future.
Adds documentation for various things that I understand. Adds #[allow(missing_doc)] for lots of things that I don't understand.
bors
added a commit
that referenced
this pull request
May 30, 2013
These commits perform a variety of actions: 1. The linting of missing documentation has been consolidated under one `missing_doc` attribute, and many more things are linted about. 2. A test was added for linting missing documentation, which revealed a large number of corner cases in both linting and the `missing_doc` lint pass. Some notable edge cases: * When compiling with `--test`, all `missing_doc` warnings are suppressed * If any parent of the current item has `#[doc(hidden)]`, then the `missing_doc` warning is suppressed 3. Both the std and extra libraries were modified to `#[deny(missing_doc)]` by default. I believe that the libraries are getting to the point where they're fairly well documented, and they should definitely stay that way. If developing a particular new module, it's easy enough to add `#[allow(missing_doc)]` at the top, but those should definitely be flags for removal in favor of actual documentation. I added as much documentation as I could throughout std/extra, although I avoided trying to document things that I knew nothing about. I can't say that this lint pass will vouch for the quality of the documentation of std/extra, but it will certainly make sure that there's at least some describing words. That being said, I may have a different opinion, so I don't mind amending these commits to turn off the lint by default for std/extra if people think otherwise.
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.
These commits perform a variety of actions:
missing_docattribute, and many more things are linted about.missing_doclint pass. Some notable edge cases:--test, allmissing_docwarnings are suppressed#[doc(hidden)], then themissing_docwarning is suppressed#[deny(missing_doc)]by default.I believe that the libraries are getting to the point where they're fairly well documented, and they should definitely stay that way. If developing a particular new module, it's easy enough to add
#[allow(missing_doc)]at the top, but those should definitely be flags for removal in favor of actual documentation.I added as much documentation as I could throughout std/extra, although I avoided trying to document things that I knew nothing about. I can't say that this lint pass will vouch for the quality of the documentation of std/extra, but it will certainly make sure that there's at least some describing words.
That being said, I may have a different opinion, so I don't mind amending these commits to turn off the lint by default for std/extra if people think otherwise.