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

Warn on missing "Errors" section in docs for Result/Option returning methods. #4854

Closed
Lokathor opened this issue Nov 28, 2019 · 3 comments · Fixed by #4884
Closed

Warn on missing "Errors" section in docs for Result/Option returning methods. #4854

Lokathor opened this issue Nov 28, 2019 · 3 comments · Fixed by #4884
Labels
A-lint Area: New lints good-first-issue These issues are a good way to get started with Clippy L-style Lint: Belongs in the style lint group

Comments

@Lokathor
Copy link

Lokathor commented Nov 28, 2019 •
edited by flip1995
Loading

Recently clippy added a warning for missing "Safety" sections in public unsafe methods/functions.

I'd like to see a similar thing for methods/functions that return Option or Result but don't have a "Errors" section in their doc.

(allow by default of course, we don't want to give people a heart attack)
@flip1995
Copy link
Member

flip1995 commented Nov 28, 2019 •
edited
Loading

Referencing Commonly Used Sections of the rust book:

Errors: If the function returns a Result, describing the kinds of errors that might occur and what conditions might cause those errors to be returned can be helpful to callers so they can write code to handle the different kinds of errors in different ways.

So we should suggest an Errors section. Not sure if we should trigger this lint for Option, since this is not mentioned/recommended in the Rust book.

@flip1995 flip1995 changed the title Warn on missing "Failure" section in docs for Result/Option returning methods. Warn on missing "Errors" section in docs for Result/Option returning methods. Nov 28, 2019
@flip1995 flip1995 added L-style Lint: Belongs in the style lint group good-first-issue These issues are a good way to get started with Clippy A-lint Area: New lints labels Dec 3, 2019
@RobbieClarken
Copy link
Contributor

I'm keen to work on this issue if no-one else has picked it up.

@flip1995
Copy link
Member

flip1995 commented Dec 4, 2019

It's all yours. You can have a look at #4535 on how to go about implementing this.

RobbieClarken added a commit to RobbieClarken/rust-clippy that referenced this issue Dec 6, 2019
@RobbieClarken
Add lint for pub fns returning a Result without documenting errors
745feff 
The Rust Book recommends that functions that return a `Result` type have
a doc comment with an `# Errors` section describing the kind of errors
that can be returned
(https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html#commonly-used-sections).
This change adds a lint to enforce this. The lint is allow by default;
it can be enabled with `#![warn(clippy::missing_errors_doc)]`.

Closes rust-lang#4854.
RobbieClarken added a commit to RobbieClarken/rust-clippy that referenced this issue Dec 6, 2019
@RobbieClarken
Add lint for pub fns returning a Result without documenting errors
1d5f7aa 
The Rust Book recommends that functions that return a `Result` type have
a doc comment with an `# Errors` section describing the kind of errors
that can be returned
(https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html#commonly-used-sections).
This change adds a lint to enforce this. The lint is allow by default;
it can be enabled with `#![warn(clippy::missing_errors_doc)]`.

Closes rust-lang#4854.
@RobbieClarken RobbieClarken mentioned this issue Dec 6, 2019
Merged
RobbieClarken added a commit to RobbieClarken/rust-clippy that referenced this issue Dec 6, 2019
@RobbieClarken
Add lint for pub fns returning a Result without documenting errors
3b71ee4 
The Rust Book recommends that functions that return a `Result` type have
a doc comment with an `# Errors` section describing the kind of errors
that can be returned
(https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html#commonly-used-sections).
This change adds a lint to enforce this. The lint is allow by default;
it can be enabled with `#![warn(clippy::missing_errors_doc)]`.

Closes rust-lang#4854.
bors added a commit that referenced this issue Dec 6, 2019
@bors
Auto merge of #4884 - RobbieClarken:warn-missing-errors, r=llogiq
61b19a1 
Add lint for pub fns returning a `Result` without documenting errors

The Rust Book recommends that functions that return a `Result` type have [a doc comment with an `# Errors` section](https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html#commonly-used-sections) describing the kind of errors that can be returned. This change adds a lint to enforce this. The lint is allow by default; it can be enabled with `#![warn(clippy::missing_errors_doc)]`.

Closes #4854.

changelog: adds lint for `missing_errors_doc`
@bors bors closed this as completed in f5d0a45 Dec 6, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
A-lint Area: New lints good-first-issue These issues are a good way to get started with Clippy L-style Lint: Belongs in the style lint group
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Add lint for pub fns returning a Result without documenting errors RobbieClarken/rust-clippy
3 participants
@RobbieClarken @Lokathor @flip1995