I've never used Doxygen before. Looks very interesting, and I will read up on it. At a cursory glance, it looks handy already for a few of my open projects.

A few more notes on doxygen:

Doxygen comes with a very useful helper program called Doxywizard that allows to create a sane and well-documented Doxyfile with a few mouse clicks. Switching it to expert mode allows all kinds of fine-tuning. Plus, you can try all changes without actually changing the Doxyfile (Doxywizard feeds the configuration into doxygen from memory via STDIN).

It is very recommended to install Graphviz. It creates useful (and very impressive) call graphs, class diagrams, and much more. All from normal code with doxygen comments, without any extra work (except for the computer). Our clients are regularily impressed by the amount of source code documentation that we generate. Most of that is automatically generated by doxygen and graphviz.

We keep the Doxyfile in subversion and add a batch file or shell script named build-docs to automatically generate the documentation in HTML format in a directory docs just below the top-level directory of the project. Next to the script, we have a README.html that explains that doxygen needs to be installed, build-docs has to be started, and then links to where doxygen creates its output.

The doxygen HTML output works much better with Javascript enabled. If you open the documentation from a filesystem (i.e. via a file:// URL), a modern browser will usually disable Javascript for security reasons. You may wish to add an exception or run a tiny webserver for viewing the documentation.

Alexander

--
Today I will gladly share my knowledge and experience, for there are no sweeter words than "I told you so". ;-)

In reply to Re^3: (How) Do you document/test your private subroutines? by afoken
in thread (How) Do you document/test your private subroutines? by stevieb

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.