[rustdoc] doesn't document method implemented in const item blocks.

[rustonaut]

Rustdoc doesn't document method implemented in const _:() = {} blocks.

(They don't show up at all.)

Minified example:

pub struct A(u8);

// this brakes rustdoc but is valid and useful in larger impl helper macros to limit imports to the macro body.
const _: () = {
    impl A {
        // YES THIS LINE IS NO doc comment, the method doesn't even show up at all
        pub fn new(inner: u8) -> Self {
            Self(inner)
        }
    }
};

// just to show the method is implemented
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn a_has_new() {
        let _ = A::new(12);
    }
}

I expected to see this happen: A::new to show up in rustdoc (without any doc comment)

Instead, this happened: A::new is not visible at all in the generated documentation.

Why is it important that rustdoc documents such items.

const _:() = {} blocks are currently the only way to have scopes on top-level items which are necessary
for producing cleaner code by e.g. grouping imports with impl. blocks or easily feature gating multiple
impl's and imports without needing to repeat the #[cfg(...)] on each item (making changes easy to accidentally partial brake code by forgetting a place where it changed).

I personally did run into this when I had a large amount of methods and traits implemented very similar on two types, where for various reasons a shared trait was not possible (and not appropriate either). I used const _:()={} to make sure the imports for the many method and trait impl.s do stay inside of the macro and do not pollute the outer scope. As far as I know this trick is also not uncommon for proc-macros.

Meta

appears on 1.47, stable, beta, nightly:

rustc 1.47.0 (18bf6b4f0 2020-10-07)
binary: rustc
commit-hash: 18bf6b4f01a6feaf7259ba7cdae58031af1b7b39
commit-date: 2020-10-07
host: x86_64-unknown-linux-gnu
release: 1.47.0
LLVM version: 11.0

rustc 1.50.0 (cb75ad5db 2021-02-10)
binary: rustc
commit-hash: cb75ad5db02783e8b0222fee363c5f63f7e2cf5b
commit-date: 2021-02-10
host: x86_64-unknown-linux-gnu
release: 1.50.0

rustc 1.51.0-beta.4 (4d25f4607 2021-03-05)
binary: rustc
commit-hash: 4d25f4607015a56d18d7c6c649441608a9298845
commit-date: 2021-03-05
host: x86_64-unknown-linux-gnu
release: 1.51.0-beta.4
LLVM version: 11.0.1

rustc 1.52.0-nightly (8f349be27 2021-03-08)
binary: rustc
commit-hash: 8f349be27815d43d462a32faeb270a22a68486b6
commit-date: 2021-03-08
host: x86_64-unknown-linux-gnu
release: 1.52.0-nightly
LLVM version: 12.0.0

[jyn514]

This was added in #67877. cc @dtolnay

[dtolnay]

That PR is the underscore const itself (see screenshot), not method impls defined inside of the const definition. If it also hides associated methods that come from inside the const definition, that was not intentional.

[dtolnay]

I tested with the following small change and the associated method A::new is still not documented by rustdoc, so it's almost definitely unrelated to that PR.

- const _: () = {
+ pub const K: () = {