3 ms·
While I don't agree with the article 100%, I too am skeptical when I see documentation generated from source. A complex topic requires decomposing the informati
by MrTonyD 8y ago
While I don't agree with the article 100%, I too am skeptical when I see documentation generated from source. A complex topic requires decomposing the information into different types of information with different approaches to explain it. Not everything is "here is the API". For example there may be an important overarching conceptual model, and information which maps into it. I don't know any way to express that in any of the source program documentation tools (at least, I've never seen it done in the many hundreds of projects I've seen.) The problems go well beyond formatting and organization. (Though, some things are simple APIs where some trivial examples and some minimal text can explain it sufficiently. That does describe a lot of existing libraries.)
- kevin_thibedeau 8y agoSphinx does this better than most since it is a general purpose documentation tool first with API doc generation as an optional add on. After setting it up you can easily add manually written documentation as needed. Most importantly, you can easily cross-reference the API docs and the manual prose from each other. Doxygen and its ilk are overly focused on generated API documentation extracted from meta-comments and you rarely see them used with well organized manually written text.