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

Warn when doc comment doesn't provide code example? #43193

Closed
GuillaumeGomez opened this issue Jul 12, 2017 · 5 comments
Closed

Warn when doc comment doesn't provide code example? #43193

GuillaumeGomez opened this issue Jul 12, 2017 · 5 comments
Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools C-enhancement Category: An issue proposing an enhancement or a PR with one. T-dev-tools Relevant to the dev-tools subteam, which will review and decide on the PR/issue.

Comments

@GuillaumeGomez
Copy link
Member

GuillaumeGomez commented Jul 12, 2017

It was during the last rustdoc reunion, I emitted the following idea:

if a doc comment doesn't have a block code (aka code example), then it emits a warning
(but only when running rustdoc)

So we have the two following ideas for the implementation:

  • rustdoc --check
  • Add another lint disabled by default (activating with #[warn(docs_without_examples)])

Any preference?

cc @rust-lang/docs
cc @ubsan

@steveklabnik steveklabnik added C-enhancement Category: An issue proposing an enhancement or a PR with one. T-dev-tools Relevant to the dev-tools subteam, which will review and decide on the PR/issue. A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools labels Jul 12, 2017
@kennytm
Copy link
Member

kennytm commented Jul 12, 2017

The lint/check should be exclude struct fields and enum variants. Maybe const and type alias as well.

Doc comments on private items should also be exempt.

I'm afraid there will still be a lot of #[allow(docs_without_examples)], like adding an example to std::ops::Add::add in additional to std::ops::Add would be just noise.

This should be doable in Clippy.

@mcarton
Copy link
Member

mcarton commented Jul 12, 2017

I had started something like that and also other Rust guidelines for documentation in Clippy a few weeks ago, never had the time to finish 😕
@kennytm makes a good point about Add vs. Add::add though.

@clarfonthey
Copy link
Contributor

clarfonthey commented Oct 8, 2017

See also rust-lang/rust-clippy#1454

@steveklabnik
Copy link
Member

Triage: nominating for future docs team discussion; people are very split about if this should be in rustdoc or clippy

@QuietMisdreavus
Copy link
Member

We talked about this in the docs team meeting today, and decided this would be better served as a lint in clippy, rather than trying to pull it into rustc immediately, or adding an entirely new interaction mode to rustdoc. As such, I'll close this issue in favor of the clippy issue @clarcharr linked earlier.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools C-enhancement Category: An issue proposing an enhancement or a PR with one. T-dev-tools Relevant to the dev-tools subteam, which will review and decide on the PR/issue.
Projects
None yet
Development

No branches or pull requests

6 participants