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 :)