Post History

Source: https://writers.stackexchange.com/a/33573
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

Source: https://writers.stackexchange.com/a/33573
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

Doxygen, etc. do not really generate documentation automatically. They restructure and format information that was written by hand, either in the form of code (which is a form of structured data) or comments written into the code. They format and publish the information automatically. They don't generate content automatically.

To me, the most glaring limitation of these tools is that they constitute a separate publishing tool chain unrelated to the tool chain used for the rest of the documentation set. This means first that you have to do all the work of configuring and maintaining the toolchain and the presentation and and formatting of your content twice. And because these all have relatively crude publishing engines, you often can't really get their output to match the design of the rest of the documentation set.

The second problem with this is that it means there is no integration between the content they produce and the rest of your content. Back in the paper days this was less of a concern, but now that we publish mainly to the Web, it makes it more difficult to do elementary things likes generating links from mentions of a function in the programmers guide to the listing of that function in the API reference.

The cure for these problems is to take XML output from these tools and to feed it into the general tool chain. Of course, this supposes that your general tool chain is XML based or is at least capable of receiving and integrating an XML feed. This is not the case for most off the shelf writing and publishing tools. The result is that your API docs are left as an island.

Original score: 10