rustdoc: new lint for warning when docs don't have an example

[QuietMisdreavus]

Per discussion on Twitter, it would be nice for rustdoc to be able to warn if an item's documentation doesn't include examples. Since we already have the infrastructure to support rustdoc-only lints (see intra-doc-link-resolution-failure) this should only need to ensure it has the same setup at that.

cc @Manishearth @yoshuawuyts

[yoshuawuyts]

I'd love to work on this if I could get some pointers on where to start! ✨

[Manishearth]

So the clean way to do it would be to add a new pass that visits the entire crate and throws warnings when it doesn't find tests.

However, this means we would be parsing markdown a third time. If we want to avoid that, we can piggyback on the intra doc links pass

We parse the markdown here. We can make markdown_links additionally look for Tag::CodeBlock when parsing there, and via LangString::parse check if it's a non-ignored rust block. Include whether or not we found one of these in the return value, and check it during the intra doc links pass. We can then emit the lint on the node id. (see this example of a lint being thrown -- you'll need to define your own lint in librustc/lint/builtin.rs)

We'd probably rename markdown_links to markdown_links_and_rust_tests and have it return something nice like a struct instead of a tuple.

Alternatively we can do it the clean-but-expensive way and have a new pass. Thoughts @QuietMisdreavus ?

[GuillaumeGomez]

A third option would be to register actions (whatever the kind of an action would be) and then call all actions on a parsed markdown block. Therefore, intra doc links pass would become an action as well and it would allow us to generalise it a bit more. What do you think of it @Manishearth?

[GuillaumeGomez]

I have a code working. I'll clean it up tomorrow and then open the PR. Afterward, it'd be nice to talk about the "rustdoc lint strategy". Putting them all behind a rustdoc lint like we have for rustc would be convenient for many people.