[Doxygen-users] Re: Here are the graphic details

[Christopher B. <bre...@ya...>]

I'm interested to see that another tech writer is
using Doxygen (any others here?). Also I'd like to
know if other people have needed to get detailed about
the formatting effects of the Dox tags.

--- Glenn Maxey <gle...@vo...> wrote:
> So, my advice to you is to:
> 
> (1) Pick a comment style closer to what the
developers are using (as in //!) .

> (3) Use slightly less leading whitespace so it is
easier for the engineers to maintain.

The style shown in my file resulted from trying to be
compatible with existing standards here.  I was 
trying to sell the idea of Doxygen, and I thought it
would go over better if the new parts fit this style.
Most classes and methods in the system aren't part of
the API and are commented with the kind of block shown
in my file: "//" comment characters with 25-space
indents for text. 

For the Dox blocks I used the Javadoc style, since
this is at least a familiar precedent if not a
standard. I wanted it to be distinct from other
commenting. You're right about the reliability of the
comment and tag style; I might change a few things
next time.

I agree with your reservations about the indent but
the programmers have been doing it for years here. For
my work, I have a routine in Word that adds the
comment symbols and indents with correct wrapping, and
reformats it correctly if I change the text. The code
didn't get too much bigger when I replaced the old
comment blocks with Dox (well, it did in a few
places).

> use the @brief tag.
> I do not follow this immediately with the detailed
description (if there
> is one) but instead insert the parameters instead.
When this is output
> in HTML and the prototype gets placed in front of
the brief decription,
> this little trick keeps the very important parameter
descriptions (USED
> DAILY by the engineer) closer to the prototype. 

I try to keep the part before the parameters to just a
modest paragraph (you wouldn't know it from my sample
file). Anything else comes later, which is often when
all that formatting detail is needed.

Christopher Brewster

__________________________________________________
Do You Yahoo!?
Yahoo! GeoCities - quick and easy web site hosting, just $8.95/month.
http://geocities.yahoo.com/ps/info1