Tamas Rudnai wrote:

> Is anybody uses doxyGen for documenting code? 
> 
> I just started to use it and could not find any information about how
> to produce a main page -- except that you have to put everything in
> source files as comments so that if you need to write some chapters
> onto the main page (or any other related pages) then you have to
> create a header file (or some other source file) that contains
> doxyGen formatted comments only. 
> 
> I found it ugly to put everything into .h files so if you have any
> better idea? Also if you know any tool for automatically generating
> indexes to anchors / function documents?

Doxygen is for documenting the code that you write. It's main purpose is
to extract the code structure, embedded comments and create a document
from this that is better readable than the pure code. This it does
rather well, IMO.

The first FAQ <http://www.stack.nl/~dimitri/doxygen/faq.html> shows how
to get some text onto the main page (\mainpage). When you, for example,
write a library, you generally already have a main include file. This
would be the one where you put this. \htmlinclude and \page may also be
helpful. 

Doxygen has quite a few commands and configuration options; I recommend
reading at least the reference section more than once, completely. This
doesn't take too long :) For getting the most benefit out of it, I think
it is also important that you experiment a bit with the code, its markup
and the Doxygen configuration until you get your code documentation to
look like you want it -- and then consistently use the same form for all
your code.

FWIW, I never create header files with Doxygen text only. I use the
header files that I already use in my code to document the code that I
write. The only thing that's different with using Doxygen is that I add
the appropriate tags for extraction, and that I do this in a more formal
and consistent way.

Doxygen extracts a documentation of the structure of your code. If you
don't like what you see, chances are that either you haven't used it
appropriately (tags or configuration not to your liking) or that the
structure of the code is not to your liking :)

Gerhard
-- 
http://www.piclist.com PIC/SX FAQ & list archive
View/change your membership options at
http://mailman.mit.edu/mailman/listinfo/piclist