|
|
|
|
|
In order to achieve all of the benefits that Doxygen can offer, you will need support and buy-off from your software engineering organization. They will have to:
Change their code commenting standards to allow comment extraction.
Give the technical writer write-access to their source code.
A template will be needed that defines the minimum amount of information and how it should be laid out. Consistency is important in API documentation.
Because the technical writer has much to gain by having Doxygen incorporated into the development process, it behooves them to volunteer for much of the work in first getting Doxygen employed. It is easier to get buy-off of others if they arent the ones doing the work.
The technical writer needs to:
Assist defining the template that is to be used in the source code for comments. Remember that the engineers own the code.
» Be flexible in the comment styles (//! versus /** ... **/)
» Be flexible in the ordering of information in the templates.
» Dont give in on things (like @ingroup) that improve the usability of the generated HTML to a wider audience.
Make a pass through all exposed source files to change existing code comments into the new format.
Make passes through the code at the engineers request to edit their comments.
|
|
|
Open-Source tools compliments of Voyant Technologies, Inc. and Glenn C. Maxey.
01/13/2003
TP Tools v2-00-0a
# tpt-hug-02