Documentation/Markdown Lints

[killercup]

I think I already mentioned this some-where some-time some-how ago, but it just came to my mind again. Basically, I'm asking: How much of RFC 505 ("API Comment Conventions") and possibly the still in-progress RFC 1574 ("More API documentation conventions") can be automated?

I think the basic rules in RFC 505 can be automated (assuming the AST has this kind of information, of course). Here's a short recap:

• Use line comments
• Only use //! for crate level comments
• "The first line in any doc comment should be a single-line short sentence providing a summary of the code." (Lint max length of 100)
• Use heading level 1
• Use common heading names (Examples, Panics, Failure). A bit of brute-force matching should suffice for usable suggestions (e.g. Example → Examples)
• Add language annotations to code examples (i.e., warn when plain ``` is found)
• Use references instead of inline links

There are some rules that require us to actually parse english (we should not try to do that):

• "All doc comments, including the summary line, should be properly punctuated. Prefer full sentences to fragments."
• "The summary line should be written in third person singular present indicative form."

Back in April, I ported some trivial lints for English texts to Rust (crates.io). It might make sense to use this, but it can also get noisy really fast. (Though the new error message layout should make multiple annotations per line look pretty nice.)

All those lints only deal with doc comments, but might also work for random Markdown files. They should be Allow by default.

---

Also, if you were to create a new lint group for this (i.e. lints dealing with Markdown instead of Rust code), it should be called Rover, clippy's docdog friend :)

[Manishearth]

We actually have a pretty awesome MD lint that actually parses the MD and does stuff with it. We don't catch much of what you list above, but we could. Some of it, like doc comment style, sounds better suited for rustfmt. But overall +1

[ghost]

"All doc comments, including the summary line, should be properly punctuated. Prefer full sentences to fragments."

Well, do we actually need to parse English for this? I think simply checking whether the summary ends with a full stop is enough and covers the majority of cases.

"The summary line should be written in third person singular present indicative form."

Simply nudging people to write /// Returns instead of /// Return would go a long way towards getting people to use that form. It's the most common deviation from the doc guidelines, after all.

We don't need advanced technology for detecting bad grammar - just checking for the most common mistakes would already be pretty useful.

[killercup]

Hi @stjepang! Since opening this issue in June 2016, the following happened:

• Clippy switched to using pulldown-cmark to parse documentation in Rewrite doc_markdown to use pulldown-cmark #1799
• I wrote this blog post proposing more conventions (can be read as Pre-RFC)
• I wrote this tool to parse documentation strings (also using pulldown-cmark), with some recent contributons from @mcarton
• I also wrote an "english-lint" crate which could probably gain a "this is probably not in 3rd person" lint