[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [avr-libc-commit] avr-libc ChangeLog doc/api/faq.dox doc/api/libr...
From: |
Joerg Wunsch |
Subject: |
Re: [avr-libc-commit] avr-libc ChangeLog doc/api/faq.dox doc/api/libr... |
Date: |
Thu, 20 Dec 2007 15:38:20 +0100 |
User-agent: |
Mutt/1.5.11 |
As Joerg Wunsch wrote:
> Log message:
> Resolve all doxygen warnings except the "is not documented" ones.
A good number of doxygen warnings have been sneaking in during the
past months. Here's just an overview so we can avoid the warnings
in future:
. If you want to empasize something, use correct markup (often only
the HTML style is useful). Instead of saying
Use <foo> to declare your foo.
write
Use <em>foo</em> to declare your foo.
If it's a complete word to emphasize, you can also use Doxygen-style
markup:
Use \e foo to declare your foo.
The HTML markup has the advantage that it can appear in the middle of
a word, so you can e.g. say
Add the option \c -mmcu=<em>mcu</em> to your command-line.
. Use \e or <em>...</em> for an emphasis, use \c or <tt>...</tt> to
indicate things that are displayed as they are typed (computer
commands, C code, ...).
. Verify your doxygen command actually is one. For example, \i simply
does not exist at all (most likely, the intention was to use italics
which is expressed as \e, resp. emphasis).
. Take care to not have certain stray characters in the code.
Candidates are <>\# which all needs to be prepended a backslash.
. Doxygen comands are case sensitiv, so it's \note rather than
\Note.
The "is not documented" warnings are not so easy to come by, since we
certainly don't want to document every internal detail. Alas, the
amount of warnings generated by these easily hide the more important
ones.
Actually, there's a few more warnings left, starting with this one:
/design/user/jwunsch/src/avr-libc/libc/stdio/ultoa_invert.S:184: Warning: Found
';' while parsing initializer list! (doxygen could be confused by a macro call
without semicolon)
This file causes further warnings because Doxygen simply cannot handle
the assembly code at all. It should probably not be processed at all.
Right now, we've got *.S in the pattern, and there are indeed a dozen
or so assembly files that do have valid doxygen comments. I wonder
how to proceed:
. Ignore the warning since no harm is done.
. Avoid the *.S, and explicitly setup all .S files that are to be
processed while leaving the remainder out.
After these documentation fixes, I'm content with the state of HEAD,
and would finally roll it as 1.6.0 tonight (hoping that my /home
partition won't overflow again...).
--
cheers, J"org .-.-. --... ...-- -.. . DL8DTL
http://www.sax.de/~joerg/ NIC: JW11-RIPE
Never trust an operating system you don't have sources for. ;-)