Clippy lint for module docs?


There has been some discussion on Reddit about the state of the docs for some rust packages.

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 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.