[Doxygen-users] Maximizing warnings for missing doxygen

[Peter B. <pd...@ma...>]

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
pd...@ma...