Clippy lint for module docs?


#1

Hi,
There has been some discussion on Reddit about the state of the docs for some rust packages. https://www.reddit.com/r/rust/comments/act2v2/is_it_reasonable_to_think_that_rust_will_become/

In particular, the discussion focused on the fact that many rust crates have ok ‘reference’ documentation, but less ‘guide’ documentation. A few suggestions for improvement:

  • Apparently rustdoc can handle markdown files, but cargo doc doesn’t. It would be nice to fix this so that readme.md was always rendered as part of the crate docs.
  • It would be nice to have a documentation clippy lint: if there is no module documentation (or the volume of module documentation is small relative to the size of the public API?), then you get a lint suggesting adding ‘guide’ type documentation to the top of the module.

Thoughts?