Thoughts on doxygen for internal documentation

[law@redhat.com]

In message <20030115194627.GA25096@tornado.toronto.redhat.com>, Diego Novillo w
rites:
 >I have tried using doxygen to document the tree-ssa API.  Given
 >the prevalent documentation style in GCC, I find some of the
 >markers rather intrusive.
 >
 >For instance, it insists that documentation for arguments should
 >be preceded by @param.  It also doesn't understand that we refer
 >to the argument names in capitals.  This breaks the flow of the
 >comment and makes it harder to read.
 >
 >I don't mind the @brief marker that it wants for adding one liner
 >descriptions in the TOC.  But again, I'd rather not add it.  What
 >I find nice are the @file markers for describing the file.
 >
 >What is really useful about doxygen is all the cross referencing
 >and html pages it builds.  Also, we don't really need to mark up
 >everything for doxygen to be useful.  It's enough that we delimit
 >the function comments with /** */.
 >
 >For the tree-ssa branch, I'd like to propose the following:
 >
 >1- When writing the preceding documentation for a function, data
 >   structure or variable, delimit it with /**  */.  This way,
 >   doxygen will add it when generating documentation.
 >
 >
 >2- For new files use the @file and @brief markers to provide a
 >   brief description for the file.
 >
 >No other markers should be required.  It would be nice if the
 >rest of the compiler used the /** */ comments, but for now I'm
 >happy if we just do it for the tree-ssa files.
Actually, I wouldn't go with doxygen stuff at all unless it's been
OK'd for the rest of the compiler proper.


jeff