Detect documentation that is empty

[i509VCB]

What it does

Detects documentation that is empty.

Lint Name

empty-docs

Category

suspicious

Advantage

• Empty docs are often pointless
• The developer may have forgotten to fill in the documentation.

Drawbacks

• Could result in the commonly used missing_docs lint being fired. However it should be possible to just use the attribute #[allow(missing_docs)] where needed.
• If #[forbid(missing_docs] is enabled, removing the empty doc comments will fire the lint.
• What applies as "empty documentation" would need to consider whitespace and possibly odd characters. Using str::is_whitespace would probably satisfy that case.

Example

//!

Could be written as (if #![warn(missing_docs)] or #![deny(missing_docs)]):

#![allow(missing_docs)]

or a message:

help: fill in the documentation

Could be written as (if missing_docs is not enabled)

If #[forbid(missing_docs)], then we probably should advise changing forbid to deny or show the message to fill in the documentation.

[xFrednet]

@rustbot label +good-first-issue

[cgorski]

@rustbot claim

[cgorski]

I just submitted a pull request in #10152 with my initial attempt at this. I do Rust dev daily for private work, but this is my first time contributing to the project, so please have mercy.

I believe I have successfully addressed blank /// doc strings and `#[doc("")] attributes by grouping attributes together that are attached to various items, and then looking for groups that are all blank.

I have not addressed the //! blank strings as I am not certain how to fetch this item from the syntax tree at the top level. It does not seem to appear with check_item(). I have not tested it inside other structures.

I have not tested any other forms of doc strings either.

I'm looking for:

1. A general assessment of what I did and if it is on the right path to completely and correctly implementing the issue
2. Suggestions on how I could detect //! best within the current framework of what I am doing (or any framework for that matter)

Thanks, I'm excited to help out on this, looking for lots of constructive criticism.

[cgorski]

Looks like there are more cases for me to handle within functions.

I just noticed I checked in two config files that have local-specific changes - I'll make sure to remove those for the final PR.

[SET001]

@cgorski are you still working on it? If no then I can try to pick it up.

[tgross35]

Honestly, I'd call it a bit surprising that //! is suitable enough to satisfy missing_docs, I'd still call that missing. Maybe we could make empty_docs an automatic warn if missing_docs is on, with eventual plans to merge them

[SET001]

@rustbot claim

[SET001]

taking into account this - should #[doc("")] be out of scope for this lint?

[lucarlig]

@rustbot claim

[Dovchik]

cargo clippy --fix doesn't not clean https://rust-lang.github.io/rust-clippy/master/index.html#/empty_docs
Should I report it as an issue or it's expected?