Re: [avr-libc-commit] avr-libc ChangeLog doc/api/faq.dox doc/api/libr...

[Joerg Wunsch]

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. ;-)