doxygen-users

[Doxygen-users] Hard to find errors

[Paul F. <pa...@fr...>]

Hi

With Doxygen 1.6.1 I have a couple of errors that look like

<unknown>:0: Warning: end of comment block while expecting command </em>
(twice)

and

<adms_checkpoint>:1: Warning: argument 'exec' of command @param is not found in
the argument list of adms_checkpoint(char *filename, howT how)
(many times, with other arguments)

Till now I've usually found that such errors are due to "stray" comments that
predated our use of Doxygen and just happened to match some markup patterns.
Finding them is usually somewhat empirical, trying to remove anything in or
around the files (or files containing the functions) until the error goes away.
However, these two have now been around for a few months (our code base is over
a million LOC, and I only run Doxygen twice a week).

Does anyone have any ideas as to how I could track down these errors?

A+
Paul
-- 
Paul Floyd   http://paulf.free.fr

Re: [Doxygen-users] Hard to find errors

[René S. <Ren...@ag...>]

forgot to post to list

René Staffen schrieb:
> 
> Paul Floyd schrieb:
>> Hi
>>
>> With Doxygen 1.6.1 I have a couple of errors that look like
>>
>> <unknown>:0: Warning: end of comment block while expecting command </em>
>> (twice)
>>
>> and
>>
>> <adms_checkpoint>:1: Warning: argument 'exec' of command @param is not found in
>> the argument list of adms_checkpoint(char *filename, howT how)
>> (many times, with other arguments)
> this one is easy.
> you dokumented a parem (with keyword @param) that does not exist
> 
> example:
> 
> good:
> /**
>  * creates a checkpoint
>  * @param filename  the filename o checkpoint
>  * @param how       what ever
>  */
> adms_checkpoint(char *filename, howT how)
> 
> 
> bad:
> /**
>  * creates a checkpoint
>  * @param anyOtherWordThanFilenameOrHow  some text
>  * @param anyOtherWordThanHowOrFilename  some text
>  */
> adms_checkpoint(char *filename, howT how)
> 
> 
>> Till now I've usually found that such errors are due to "stray" comments that
>> predated our use of Doxygen and just happened to match some markup patterns.
>> Finding them is usually somewhat empirical, trying to remove anything in or
>> around the files (or files containing the functions) until the error goes away.
>> However, these two have now been around for a few months (our code base is over
>> a million LOC, and I only run Doxygen twice a week).
>>
>> Does anyone have any ideas as to how I could track down these errors?
>>
>> A+
>> Paul
> 

-- 

Dipl.-Inf. (FH) René Staffen
Softwareentwickler
eMail: Ren...@ag...
Tel:   +49 (0)30 2000 429 332


Hella Aglaia Mobile Vision GmbH
Treskowstr. 14
D-13089 Berlin
Amtsgericht Berlin-Charlottenburg HRB 66976
Geschäftsführer: Thomas Schilling

URL:  www.aglaia-gmbh.de
URL:  www.mobilevision.de

Dieses Dokument ist vertraulich zu behandeln.
Die Weitergabe sowie Vervielfältigung, Verwertung und Mitteilung
seines Inhalts ist nur mit unserer ausdrücklichen Genehmigung gestattet.
Alle Rechte vorbehalten, insbesondere für den Fall der Schutzrechtsanmeldung.

This document has to be treated confidentially.
Its contents are not to be passed on, duplicated, exploited or disclosed
without our express permission. All rights reserved,
especially the right to apply for protective rights.

Re: [Doxygen-users] Hard to find errors

[Paul F. <pa...@fr...>]

Quoting René Staffen <Ren...@ag...>:
> this one is easy.

If only :-(

> you dokumented a parem (with keyword @param) that does not exist

The function isn't documented at all:

DLLEXPORT void adms_checkpoint(char *filename, howT how);

and in any case, why is Doxygen complaining about arguments like "exec" when the
two arguments are called "filename" and "how"?

<adms_checkpoint>:1: Warning: argument 'exec' of command @param is not found in
the argument list of adms_checkpoint(char *filename, howT how)

A+
Paul
-- 
Paul Floyd   http://paulf.free.fr

Re: [Doxygen-users] Hard to find errors

[Evan P. <ewp...@gm...>]

Do you have this function defined in a header and a source file? You may have conflicting comment blocks.

Evan

On Dec 4, 2009, at 10:15 AM, Paul Floyd wrote:

> 
> Quoting René Staffen <Ren...@ag...>:
>> this one is easy.
> 
> If only :-(
> 
>> you dokumented a parem (with keyword @param) that does not exist
> 
> The function isn't documented at all:
> 
> DLLEXPORT void adms_checkpoint(char *filename, howT how);
> 
> and in any case, why is Doxygen complaining about arguments like "exec" when the
> two arguments are called "filename" and "how"?
> 
> <adms_checkpoint>:1: Warning: argument 'exec' of command @param is not found in
> the argument list of adms_checkpoint(char *filename, howT how)
> 
> A+
> Paul
> -- 
> Paul Floyd   http://paulf.free.fr
> 
> ------------------------------------------------------------------------------
> Join us December 9, 2009 for the Red Hat Virtual Experience,
> a free event focused on virtualization and cloud computing. 
> Attend in-depth sessions from your desk. Your couch. Anywhere.
> http://p.sf.net/sfu/redhat-sfdev2dev
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users

Re: [Doxygen-users] Hard to find errors

[Paul F. <pa...@fr...>]

Quoting Evan Patton <ewp...@gm...>:

> Do you have this function defined in a header and a source file? You may have
> conflicting comment blocks.

I can't see any, but I think that I'm getting closer to this one. One of our
developers has been using @def with functions (thinking that it means
'definition' not 'define'). Obviously this confused Doxygen, and for some reason
the function 'adms_checkpoint' was the lucky recipient of all the markup.

I've cleaned all that, and will know in an hour or two if that fixes it.

A+
Paul
-- 
Paul Floyd   http://paulf.free.fr

Re: [Doxygen-users] Hard to find errors

[Ger v. D. <di...@as...>]

Hi Paul,

I found that doxygen (1.5.7) has problems with a dot in an em block.
E.g. the following gives the errors:

/Users/diepen/casacore-old/doxyproblem.hh:13: Warning: end of comment block while expecting command </em>
/Users/diepen/casacore-old/doxyproblem.hh:13: Warning: end of comment block while expecting command </em>
/Users/diepen/casacore-old/doxyproblem.hh:12: Warning: found </em> tag without matching <em>

while it is fine when removing the dot. The same seems to be the case for <tt>.
I've reported it on April 11th 2008, but got no reply.

Cheers,
Ger


#ifndef CASA_QUANTUM_H
#define CASA_QUANTUM_H

namespace casa { //# NAMESPACE CASA - BEGIN

/** \ingroup Quantum 
\brief 
    Quantities (i.e. dimensioned values)
    */
template <class Qtype> class Quantum {
 public:
  /** <em> The dot at the end gives em problems. </em>
  */
  static Bool read(Quantity &res, MUString &in);
};
} //# NAMESPACE CASA - END



>>> On Fri, Dec 4, 2009 at  3:49 PM, in message
<125...@im...>, Paul Floyd <pa...@fr...> wrote: 
> Hi
> 
> With Doxygen 1.6.1 I have a couple of errors that look like
> 
> <unknown>:0: Warning: end of comment block while expecting command </em>
> (twice)
> 
> and
> 
> <adms_checkpoint>:1: Warning: argument 'exec' of command @param is not found 
> in
> the argument list of adms_checkpoint(char *filename, howT how)
> (many times, with other arguments)
> 
> Till now I've usually found that such errors are due to "stray" comments 
> that
> predated our use of Doxygen and just happened to match some markup patterns.
> Finding them is usually somewhat empirical, trying to remove anything in or
> around the files (or files containing the functions) until the error goes 
> away.
> However, these two have now been around for a few months (our code base is 
> over
> a million LOC, and I only run Doxygen twice a week).
> 
> Does anyone have any ideas as to how I could track down these errors?
> 
> A+
> Paul

Re: [Doxygen-users] Hard to find errors

[Ger v. D. <di...@as...>]

After some more digging with a colleague I found why it was giving that warning.
I used JAVADOC_AUTOBRIEF=YES, so the first sentence (until the dot) was handled as the brief comment.

Cheers,
Ger

>>> On Fri, Dec 4, 2009 at  4:06 PM, in message <4B1...@as...>,
"Ger van Diepen" <di...@as...> wrote: 
> Hi Paul,
> 
> I found that doxygen (1.5.7) has problems with a dot in an em block.
> E.g. the following gives the errors:
> 
> /Users/diepen/casacore-old/doxyproblem.hh:13: Warning: end of comment block 
> while expecting command </em>
> /Users/diepen/casacore-old/doxyproblem.hh:13: Warning: end of comment block 
> while expecting command </em>
> /Users/diepen/casacore-old/doxyproblem.hh:12: Warning: found </em> tag without 
> matching <em>
> 
> while it is fine when removing the dot. The same seems to be the case for 
> <tt>.
> I've reported it on April 11th 2008, but got no reply.
> 
> Cheers,
> Ger
> 
> 
> #ifndef CASA_QUANTUM_H
> #define CASA_QUANTUM_H
> 
> namespace casa { //# NAMESPACE CASA - BEGIN
> 
> /** \ingroup Quantum 
> \brief 
>     Quantities (i.e. dimensioned values)
>     */
> template <class Qtype> class Quantum {
>  public:
>   /** <em> The dot at the end gives em problems. </em>
>   */
>   static Bool read(Quantity &res, MUString &in);
> };
> } //# NAMESPACE CASA - END
> 
> 
> 
>>>> On Fri, Dec 4, 2009 at  3:49 PM, in message
> <125...@im...>, Paul Floyd <pa...@fr...> wrote: 
>> Hi
>> 
>> With Doxygen 1.6.1 I have a couple of errors that look like
>> 
>> <unknown>:0: Warning: end of comment block while expecting command </em>
>> (twice)
>> 
>> and
>> 
>> <adms_checkpoint>:1: Warning: argument 'exec' of command @param is not found 
>> in
>> the argument list of adms_checkpoint(char *filename, howT how)
>> (many times, with other arguments)
>> 
>> Till now I've usually found that such errors are due to "stray" comments 
>> that
>> predated our use of Doxygen and just happened to match some markup patterns.
>> Finding them is usually somewhat empirical, trying to remove anything in or
>> around the files (or files containing the functions) until the error goes 
>> away.
>> However, these two have now been around for a few months (our code base is 
>> over
>> a million LOC, and I only run Doxygen twice a week).
>> 
>> Does anyone have any ideas as to how I could track down these errors?
>> 
>> A+
>> Paul
> 
> 
> ------------------------------------------------------------------------------
> Join us December 9, 2009 for the Red Hat Virtual Experience,
> a free event focused on virtualization and cloud computing. 
> Attend in-depth sessions from your desk. Your couch. Anywhere.
> http://p.sf.net/sfu/redhat-sfdev2dev
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users