kicad-developers team mailing list archive

[Wayne Stambaugh <wstambaugh@xxxxxxxxx>]

Gentlemen,

I rebuilt my Doxygen docs yesterday and noticed what seemed like an awful lot
of error and warning messages scrolling by so I dumped stderr to a file and was
a bit dismayed at all of the warnings and errors.  I fixed a bunch of them but
I only scratched the surface as part of my latest commit.  Here is a short list
of the main problems.

* Doxygen comments out of sync in header and source file make Doxygen unhappy.
* Doxygen will attempt to interpret <file> inside a comment as an HTML tag.
This needs to be changed to &ltfile&gt.  The same holds true for any other HTML
special characters.
* @info is not a valid Doxygen tag.  Use something like @note or @see.
* The WXUNUSED() macro causes warnings.  According to the macro definition in
<wx/defs.h> this macro is no longer needed so I think we can safely remove it
since most of the event arguments aren't wrapped inside WXUNUSED.
* @return none will cause Doxygen to emit a warning and doesn't add anything to
the Doxygen docs.
* Doxygen comments on methods with arguments must define all the arguments.

Please clean up Doxygen comments as you make changes to the code.  Better yet,
from your Kicad build path run:

build doxygen-docs * 2> kicad-doxygen-stderr.txt

and fix few warnings for each commit and it won't take long get this under control.

Wayne