The title says it all. But here a few points which concern me:
doxygen is a great tool for documentation. It can probably cover most of your needs. As far as customer documentation vs. internal documentation I would consider only giving customers interface classes and their documentation. The implementation detail should be considered internal and be in separate documented source files.
Generally; specify it, design it, build it. This hierarchy of abstraction will make all documentation tasks simpler, and documentation errors both more obvious and less critical. If you build it, then retrospectively document it, you will likley be in trouble. It will be hard work, it may not get done at all, and the level of detail is unlikely to be appropriate to the different audiences that need documentation (e.g. end users, developers, maintainers). Moreover your manager or other project sponsor won't know what you are building until it is finished, and going dark like that is not a good thing.
- How do you maintain documentation which will be released to customers?
Much of that can (and should) be generated from the product requirements specification and has little to do with the code (unless perhaps you are selling a library rather than an application). This has the advantage that it can be generated concurrently with development.
- What about docs which are for internals use?
MS Word for technical notes. UML for what I intend to build, Doxygen for what was actually built. Hopefully there is some correspondence between the two, but the UML model represents a road-map for developers and maintainers, whereas the Doxygen output is the detail. Detailing a UML model sufficiently to allow direct code generation is generally inefficient, though the 'round-trip' engineering capability of some tools theoretically ensures code and documentation (or rather model) are synchronised.
Often I add standalone Doxygen markup files with high level documentation that is not expressed in the code mark-up, specifically how individual interfaces are used together. This may include code examples, timing diagrams, HTML, links to external documents.
- How to document packages/classes/methods/APIs?
Doxygen
- How to ensure maintainability? e.g. check-in criteria, code review checklist item, automation.
Surely that is the real question!? The others are just about tools. Doxygen will for example issue warnings for missing or inconsistent parameter documentation and other inconsistencies or omissions. I include the Doxygen generation as an automated build-step, and treat its warnings as if they were compiler errors. In a team environment you might use a continuous integration tool to perform this, and inform developers when they check-in code that does not build documentation without warnings.