WIP: empty_doc

[SET001]

Fixes #9931

changelog: [`empty_doc`]: Detects documentation that is empty.

[rustbot]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @Alexendoo (or someone else) soon.

Please see the contribution instructions for more information. Namely, in order to ensure the minimum review times lag, PR authors and assigned reviewers should ensure that the review label (S-waiting-on-review and S-waiting-on-author) stays updated, invoking these commands when appropriate:

• @rustbot author: the review is finished, PR author should check the comments and take action accordingly
• @rustbot review: the author is ready for a review, this PR will be queued again in the reviewer's queue

[blyxyas]

Very good for a first patch ❤️, mainly just some documentation rephrasing and refactoring to fit better with the rest of the codebase 🐈

[Alexendoo]

None of these are actually empty documentation, this is ~equivalent to

//!
//! valid doc comment
//!!
//!! valid doc comment

///
/// valid doc comment
/// 
/// valid block doc comment

Because doc comments and #[doc] attributes are merged together

This really should go in doc.rs where this merging/parsing is all handled already

[SET001]

@Alexendoo according to https://doc.rust-lang.org/reference/comments.html there are one line and block doc comments.
What you show in your example is 8 separate one-line doc comments. They are not being merged in 2, just because there are no line breaks within them. So lint in this PR will trigger on lines 1, 3, 5, 6 (and I'm updating the test to demonstrate this).

As for block doc comments, I assume they might have empty lines (for formatting purposes) because the definition of empty for a block comment is when all lines are empty.

Tbh I do not understand the part about merging with #[doc] attributes. Can you please explain?

[SET001]

This really should go in doc.rs where this merging/parsing is all handled already

there is no much merging/parsing happening in this current lint. The idea is to have all doc-related lints in doc.rs?

[Alexendoo]

I'm not saying the attributes are merged in the AST/HIR, but the multiple attributes representing doc comments are merged into a single piece of documentation by rustdoc, be they line comments, block comments or #[doc = ".."] attributes

My example was to represent what rustdoc approximately sees as the documentation, not to say that doc comments get converted to line comments. A screenshot may be clearer:

    ///

    /// valid doc comment

    /**
     *
     */

    /**
     * valid block doc comment
     */

    pub mod inner_module {}

The whitespace between the doc comments are not significant, e.g.

/// a

///

/// b

is the same as

/// a
///
/// b

But we certainly don't want to lint the middle line comment, it's significant because it causes a and b to be separate paragraphs

[Alexendoo]

there is no much merging/parsing happening in this current lint. The idea is to have all doc-related lints in doc.rs?

Yeah, it could go here

rust-clippy/clippy_lints/src/doc.rs

Lines 493 to 495 in 3662bd8

	if doc.is_empty() {
	return Some(DocHeaders::default());
	}

With .is_empty() being changed to check that doc only contains whitespace if needed, you can use https://doc.rust-lang.org/nightly/nightly-rustc/rustc_resolve/rustdoc/fn.span_of_fragments.html on fragments to get the span

[rustbot]

There are merge commits (commits with multiple parents) in your changes. We have a no merge policy so these commits will need to be removed for this pull request to be merged.

You can start a rebase with the following commands:

$ # rebase
$ git rebase -i master
$ # delete any merge commits in the editor that appears
$ git push --force-with-lease

The following commits are merge commits:

• 40f3102

[bors]

☔ The latest upstream changes (presumably #11791) made this pull request unmergeable. Please resolve the merge conflicts.

[GuillaumeGomez]

I think that one shouldn't be needed.

[GuillaumeGomez]

I think there is a missing .filter(|line| !line.is_empty())

[xFrednet]

Hey @SET001, this is a ping from triage, since there hasn't been any activity in some time. Are you still planning to continue this implementation?

If you have any questions, you're always welcome to ask them in this PR or on Zulip.

@rustbot author

[y21]

Looks like this was continued in #12342 because of inactivity. The lint exists now: https://rust-lang.github.io/rust-clippy/master/index.html#/empty_docs

[xFrednet]

Thank you for the comment @y21. Then let's close this one.

@SET001 thank you for the time you put into this PR!

[SET001]

@xFrednet hi, I do not plan to continue work on this implementation. Happy that someone finally did this )