Thoughts on doxygen for internal documentation

[Diego Novillo <dnovillo at redhat dot com>]

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.


Thoughts?   Diego.