ghuntley
commented
9 years ago re: autogenerated documentation see http://jacobian.org/writing/what-to-write/
Auto-generated documentation is almost worthless. At best it’s a slightly
improved version of simply browsing through the source, but most of the time
it’s easier just to read the source than to navigate the bullshit that these
autodoc tools produce. About the only thing auto-generated documentation is good
for is filling printed pages when contracts dictate delivery of a certain number
of pages of documentation. I feel a particularly deep form of rage every time I
click on a “documentation” link and see auto-generated documentation.
There’s no substitute for documentation written, organized, and edited by hand.
I’ll even go further and say that auto-generated documentation is worse than
useless: it lets maintainers fool themselves into thinking they have
documentation, thus putting off actually writing good reference by hand. If you
don’t have documentation just admit to it. Maybe a volunteer will offer to write
some! But don’t lie and give me that auto-documentation crap.http://jacobian.org/writing/technical-style/ http://jacobian.org/writing/editors/
jthelin
gabikliot
sergeybykov
richorama
jason-bragg
ToddShelton
MovGP0
veikkoeeva
jdom
ReubenBond
Auto-generated documents can help provide more complete and up-to-date documentation with little effort.
I'm thinking first steps might be. 1) Select code generator - Doxygen? 2) Create basic configurations and script to generate reference manual like documentation.
Then we can refine the comments in code to improve the generated documents.
When generated documentation is of sufficient quality we can: 3) Incorporate document generation into the builds. 4) Add automation to publish documents online whenever repository is updated.
Thoughts?