Documentation generation. Which boxes should be ticked?

Question

I am looking for my team to more thoroughly document their code for some major upcoming projects and make life a little less painful; I turn to XML documentation generators like Sandcastle , Doxygen or Box Live Documenter .

What are the key considerations that I must consider when evaluating the best option and what experience has led you to a specific decision?

Answer 1

For me, the main considerations would be as follows:

• Fully Automated:. Can it be configured so that to a large extent no external work is required to create or edit the documentation.

• Completely style: Is it possible to fully document the documentation that it looks great on a wiki or pdf after it is generated. I should be able to change colors, font sizes, layouts, etc.

• Good filtering: You can only select the elements that I want to generate. I should be able to filter namespaces, file types, classes, etc.

• Customization: Can I include headers, footers, custom elements, etc.

I found that Doxygen could do all this. Our workflow is as follows:

• Developer makes code changes

• They update documentation tags directly above the code they just changed.

• We press the generate button

Then Doxygen will extract all the XML documentation from the code, filter it to include only the classes and methods that we want, and apply the CSS style that was previously prepared for it. Our end result is an internal wiki that looks the way we want it and does not require editing.

Extras: We have all our projects in various git repositories. We pull all this into one root folder and generate documents from this root folder.

It would be interesting to know how others are even more automated ..?

Answer 2

• Who pays for the documentation and why? (the system is stable enough, does it add enough value)
• Who is going to read it and why is it not using a more efficient communication channel? (if the correct mostly distance in time / place)
• Who will follow the updates.
• When are you going to destroy him? (Automatically if it has not been read or updated in the last three months?)

Mostly I prefer the best code to make my life less painful, more documentation, but I like scripts and unit tests and a high-level architecture description.

[edit] Documentation takes time and money to write and update. JavaDoc-style documentation has a serious negative effect on the number of simultaneously visible codes and may be a good idea for developers using this code, but not for those who write it.