undefined | Better HN

0 pointsubernostrum9y ago0 comments

So, to take an example, here's the documentation for a library I maintain:

http://webcolors.readthedocs.io/

Once upon a time, the entire library's documentation was generated from docstrings in the code, but the library very quickly outgrew that as I needed to do things like:

* How to install the library and how to run the tests

* Properly explain the web color model and the history of how it's been implemented in the specifications

* Properly explain how the various ways to specify colors get represented as Python types

* Explain how Python 2/3 compatibility is handled

etc., etc.

There are a ton of things that don't naturally attach to just one function or class, but need to be in the documentation. The hacky compromise solution is a module-level docstring, but now people who want to read source have to scroll through a huge amount of stuff before they see a single line of actual code.

So I'm going to stay far away from auto-generated documentation and "just put it in comments/docstring/etc." for the foreseeable future.

0 comments

1 comments · 1 top-level

burntsushi9y ago

I think you're throwing the baby out with the bath water, and I think module level comments are a perfectly reasonable place to address most of your concerns. (I don't know why they're "hacky.") Look for example at these docs, which are completely auto-generated from comments in the source: https://docs.rs/regex ... Here's another example: https://docs.rs/fst

Note that I do think there's a limit to what auto-documentation can provide, but I think you're selling it pretty short.

j / k navigate · click thread line to collapse