3 ms·

Documentation should be written by people, for people. Autogenerated API docs are as old and common as hills, but are so inferior that their value over readable

by pekk 10y ago

Documentation should be written by people, for people. Autogenerated API docs are as old and common as hills, but are so inferior that their value over readable Python code is negligible to nonexistent. I hope readthedocs isn't causing the Python ecosystem to abandon documentation written by humans with this emphasis on Java-style autogeneration.

burntsushi 10y ago
Could you elaborate on this? Aren't auto-generated docs produced from comments written by humans? What exactly is wrong with that?
- ubernostrum 10y ago
  So, to take an example, here's the documentation for a library I maintain: http://webcolors.readthedocs.io/ 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.
  - burntsushi 10y 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 https://docs.rs/regex ... Here's another example: https://docs.rs/fst 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.

by pekk 10y ago

burntsushi 10y ago

Could you elaborate on this? Aren't auto-generated docs produced from comments written by humans? What exactly is wrong with that?

ubernostrum 10y ago
So, to take an example, here's the documentation for a library I maintain: http://webcolors.readthedocs.io/ 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.
- burntsushi 10y 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 https://docs.rs/regex ... Here's another example: https://docs.rs/fst 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.