Hello Folks,
I need help configuring Doxygen to generate warnings on *any* undocumented
items.
There are a few cases which seem to pass without warnings, despite the obvious
Doxyfile config options. There are other cases which generate warnings for
parameters and return values, but only if the brief description ends with '.'
(We have autobrief enabled). See below for examples.
I think the relevant Doxyfile config parameters are:
> EXTRACT_ALL = NO
> EXTRACT_PRIVATE = YES
> EXTRACT_PACKAGE = NO
> EXTRACT_STATIC = yes
> EXTRACT_LOCAL_CLASSES = YES
> EXTRACT_LOCAL_METHODS = NO
> EXTRACT_ANON_NSPACES = YES
> HIDE_UNDOC_MEMBERS = NO
> HIDE_UNDOC_CLASSES = NO
> HIDE_FRIEND_COMPOUNDS = NO
> HIDE_IN_BODY_DOCS = NO
> INTERNAL_DOCS = YES
> JAVADOC_AUTOBRIEF = YES
> QT_AUTOBRIEF = YES
>
> QUIET = NO
> WARNINGS = YES
> WARN_IF_UNDOCUMENTED = YES
> WARN_IF_DOC_ERROR = YES
> WARN_NO_PARAMDOC = YES
> WARN_FORMAT = "$file:$line: $text"
> WARN_LOGFILE = doxygen.log
Are there other configuration variables I should look at? Or different values
of these variables?
Thanks,
Peter
----------
Below are some examples which fail to generate warnings. Where partial
documentation is given, it doesn't matter whether it's JavaDoc style ('/** ...
*/'), Qt style ('/*! ... */') or C++ style ('/// ...').
> // Undoc'd named namespace. // NO WARN
> namespace undoc {
>
> // Undoc'd func.
> void unsFuncUndoc (void); // warn function
>
> /** Doc'd func with undoc'd param */ // NO WARN
> void unsFuncUndocArg (int foo);
>
> /** Doc'd func with undoc'd return value */ // NO WARN
> int unsFuncUndocReturn (void);
>
> } // namespace undoc
The undocumented function gets a warning, but undocumented parameters or return
value don't. If the namespace itself is documented, all of these cases
generate warnings.
Another namespace example:
> // Undoc'd anonymous namespace. // NO WARN
> namespace {
> …
> } // anonymous namespace
Undocumented namespaces, either named or anonymous, don't seem to generate any
warnings ever.
> // Undoc'd default constructor
> class Foo {
> Foo (void); // NO WARN
> };
Constructors with parameters do generate a warning (but see below).
Here's another set which fail to generate warnings *unless the brief
description ends with '.'*
> /** \file */ // Required to trigger warnings at global scope:
>
> /** Doc'd func with undoc'd param */ // DOT WARN parameters
> void FuncUndocArg (int foo);
>
> /** Doc'd func with undoc'd return */ // DOT WARN return
> int FuncUndocReturn (void);
> // Undoc'd anonymous namespace or doc'd named namespace
> // (See above for undoc'd named namespace)
> namespace {
>
> /** Doc'd func with undoc'd param */ // DOT WARN parameters
> void ansFuncUndocArg (int foo);
>
> /** Doc'd func with undoc'd return */ // DOT WARN return
> int ansFuncUndocReturn (void);
>
> } // anonymous namespace
> class Foo
> {
>
> // public or private:
>
> /** Doc'd (public) ctor with undoc'd param */ // DOT WARN parameters
> ClassUndoc (int foo);
>
> /** Doc'd member func with undoc'd param */ // DOT WARN parameters
> void pubMemFuncUndocArg (int foo);
>
> /** Doc'd member func with undoc'd return */ // DOT WARN return
> int pubMemFuncUndocReturn (void);
(These are from a longer test file, which marks each statement with the type of
warning, or lack thereof, on the same line as reported by doxygen. I can
forward that if it would be helpful.)
Thanks,
Peter
In case versions matter: doxygen 1.8.9.1, Mac 10.8.5, gcc 4.2.1.
____________
Peter Barnes
p...@mac.com
------------------------------------------------------------------------------
Dive into the World of Parallel Programming. The Go Parallel Website,
sponsored by Intel and developed in partnership with Slashdot Media, is your
hub for all things parallel software development, from weekly thought
leadership blogs to news, videos, case studies, tutorials and more. Take a
look and join the conversation now. http://goparallel.sourceforge.net/
_______________________________________________
Doxygen-users mailing list
Doxygen-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/doxygen-users
