Documentation Generation - What boxes should I aim to tick?

I'm looking at requiring my team to document their code more thoroughly for some major upcoming projects and to make life a little less painful, I am steering towards XML documentation generators such as Sandcastle, Doxygen开发者_高级运维 or Box Live Documenter.

What are the key considerations I should keep in mind when evaluating the best option and what experiences have led you to a particular decision?

For me the key considerations would be:

1. Fully automated: Can it be set up in such a way so that pretty much no outside work is required to create or edit the documentation.

2. Fully styled: Can the documentation be fully styled so that it looks great in a wiki or pdf after it’s generated. I should be able to change colors, font sizes, layouts, etc.

3. Good Filtering: Can I select only the items I want to be generated. I should be able to filter the namespaces, file types, classes, etc.

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

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

1. Developer makes a change to the code

2. They update the documentation tags right above the code they just changed

3. We click a generate button

Doxygen will then extract all the XML documentation from the code, filter it to only include the classes and methods we want, and apply the CSS styling we’ve pre-made for it. Our end result is an internal wiki that looks the way we want, and doesn’t require editing.

Extra: We have all our projects in various git repositories. We pull all these down to one root folder and generate the docs form this root folder..

Would be interested to know how others are automating even further..?

1. Who is paying for the documentation and why? (is the system stable enough, does it add enough value)
2. Who is going to read it, and why is she not using a more effective communication channel? (if correct mostly distance in time/place)
3. Who is going to keep it up to date.
4. When are you going to destroy it? (Automatically if it hasn't been read or updated in the past three months?)

I mostly prefer better code to make my life less painful, over more documentation, but I like scenario & unit tests and a high level architecture description.

[edit] Documentation costs time and money to write and keep up to date. JavaDoc style documentation has a serious detrimental effect on the amount of code simultaneously visible and might be a good idea for the developers using the code, but not for those writing it.