Should doctests on local `let` statements be found / executed?

[TedDriggs]

Consider the following code:

#![allow(dead_code)]

fn main() {
    /// Here, we initialize our thing to two.
    ///
    /// ```
    /// panic!("oh no what does rustdoc do here");
    /// ```
    let asdf = 2;
    
    println!("hello {}!", asdf);
}

RLS and Racer would like to be able to show docs for asdf on hover in the println! statement. The markdown block in the example would successfully be desugared into a #[doc="..."] attribute, so everything seems fine. However, the doctest in this won't be found or executed today.

Tagging @QuietMisdreavus, and @Ralith, who all weighed in on IRC.

This relates to racer-rust/racer#740.

[QuietMisdreavus]

(imperio on IRC is actually @GuillaumeGomez, ftr)

[QuietMisdreavus]

cc @rust-lang/dev-tools

[oli-obk]

If they are not executed, they need to be linted about. My vote is for executing them, since that's the least surprising thing

[GuillaumeGomez]

I'm mostly in favor of this, however: why adding doc comments in code? I can't see any use for this...

[TedDriggs]

@GuillaumeGomez in IDEs, RLS/Racer would show these docs when autocompleting or hovering over local variable usages. JS and TypeScript already do this in a variety of editors (you can try it in VSCode) and in large functions or deeply-nested closures it's very useful.

@oli-obk I agree with execution-by-default as the least-surprising policy. The test would only have access to the crate's public API, but that's already true for doc-tests on non-public functions or types.

[steveklabnik]

I personally wouldn't expect doc comments to work on anything other than top-level items.

[TedDriggs]

wouldn't expect them to work

@steveklabnik do you mean they should be a compile error, or that tooling should ignore them? Making them a compiler error would break code that I (and possibly others?) have written.

[steveklabnik]

I'm surprised that they weren't a compiler error already, but given that they aren't, I agree it's not necessarily feasible to make them into an error.

I'd expect tooling to ignore them. Again, just speaking personally.

[GuillaumeGomez]

I agree with @steveklabnik. If this is needed and everyone agree on it, I'll make them go into hard error.

[TedDriggs]

That would break already-shipped code, so I don't think a hard error is a good idea.

[oli-obk]

I'm sure it would go through the warning -> deny lint -> hard error cycle

[TedDriggs]

My larger objection to disallowing comments on let statements is that denying them takes away something of value for no clear gain. RLS and Racer can both take advantage of doc attributes on let statements to show explanatory text on hover at usage sites or in completion lists.

One-line comments explaining the purpose of local variables are hardly rare in complex functions, but neither Racer nor RLS would want to try and pair regular comments up with statements for the use cases above; Racer masks comments before analysis, and I'm not sure how RLS would even see comments given that it's using the compiler for more of its data.