doxygen-users

[Doxygen-users] Two strange things about Doxygen and my code

[Bostjan M. <cco...@gm...>]

First of all, hello everyone!

I'm trying out Doxygen 1.8.10 to generate doc for my C code. I'm a but
stumped about two things, though.
Example header:

/// @file

/// My typedef.
typedef void VOID;

/// My simple function. Details.
extern VOID Function(VOID);

Note that I have enabled OPTIMIZE_OUTPUT_FOR_C, JAVADOC_AUTOBRIEF and
enabled all warnings.

The first thing is that Doxygen will generate doc for this function,
but emit no warnings and also not create a link with details (whole
line is read as brief). The problem goes away when there are at least
two lines beginning with ///. I noticed documentation states that I
need to make at least two lines in case of single-line comments. My
question is: why? Is there a special reason for it?

The second thing is that VOID typedef. When I add another /// line,
Doxygen starts to emit warnings. However, it emits missing return
value warning in this case (although there is no return value). Now, I
understand it doesn't see "void" there. If I replace "VOID" with
"void", it doesn't emit a warning. The problem is something else. I
tried to fix this by
ENABLE_PREPROCESSING = YES
PREDEFINED = VOID=void

It didn't seem to do anything, warning is still emitted. I also tried
PREDEFINED = "VOID=void"
Warning still emitted.
Am I missing something?

With kind regards,
Bostjan

Re: [Doxygen-users] Two strange things about Doxygen and my code

[Christoph L. <chr...@li...>]

Am 25.08.2015 um 18:36 schrieb Bostjan Mihoric:
[...]
> /// @file
>
> /// My typedef.
> typedef void VOID;
>
> /// My simple function. Details.
> extern VOID Function(VOID);
>
> Note that I have enabled OPTIMIZE_OUTPUT_FOR_C, JAVADOC_AUTOBRIEF and
> enabled all warnings.
>
> The first thing is that Doxygen will generate doc for this function,
> but emit no warnings and also not create a link with details (whole
> line is read as brief). The problem goes away when there are at least
> two lines beginning with ///. I noticed documentation states that I
> need to make at least two lines in case of single-line comments. My
> question is: why? Is there a special reason for it?

Yes, there is. From the docs (emphasis mine):

"For the BRIEF description there are also several possibilities:
[...]
3. A third option is to use a special C++ style comment which DOES NOT
span more than one line. [...]"

In other words, single-line C++ style comments are reserved for
autobrief comments that do _not_ stop at the first dot-whitespace
sequence as Javadoc-autobrief comments do.

(My personal preference would be for the entire first _paragraph_ to
always be considered a brief description, but alas, that's not supported.)

Re: [Doxygen-users] Two strange things about Doxygen and my code

[Bostjan M. <cco...@gm...>]

On Tue, Aug 25, 2015 at 7:14 PM, Christoph Lipka
<chr...@li...> wrote:
> Am 25.08.2015 um 18:36 schrieb Bostjan Mihoric:
> [...]
>
> /// @file
>
> /// My typedef.
> typedef void VOID;
>
> /// My simple function. Details.
> extern VOID Function(VOID);
>
> Note that I have enabled OPTIMIZE_OUTPUT_FOR_C, JAVADOC_AUTOBRIEF and
> enabled all warnings.
>
> The first thing is that Doxygen will generate doc for this function,
> but emit no warnings and also not create a link with details (whole
> line is read as brief). The problem goes away when there are at least
> two lines beginning with ///. I noticed documentation states that I
> need to make at least two lines in case of single-line comments. My
> question is: why? Is there a special reason for it?
>
>
> Yes, there is. From the docs (emphasis mine):
>
> "For the BRIEF description there are also several possibilities:
> [...]
> 3. A third option is to use a special C++ style comment which DOES NOT span
> more than one line. [...]"
>
> In other words, single-line C++ style comments are reserved for autobrief
> comments that do _not_ stop at the first dot-whitespace sequence as
> Javadoc-autobrief comments do.
>
> (My personal preference would be for the entire first _paragraph_ to always
> be considered a brief description, but alas, that's not supported.)
>

Agreed, at least when JAVADOC_AUTOBRIEF is specifically enabled it
should work like that. But what I still don't understand, why does
Doxygen then not emit warnings? Surely, having just a brief
description does not also mean "and ignore parameters and return
type"?

And why does the VOID redefine not work?

Thanks!

Re: [Doxygen-users] Two strange things about Doxygen and my code

[Christoph L. <chr...@li...>]

Am 26.08.2015 um 11:14 schrieb Bostjan Mihoric:
> On Tue, Aug 25, 2015 at 7:14 PM, Christoph Lipka
> <chr...@li...> wrote:
>> Am 25.08.2015 um 18:36 schrieb Bostjan Mihoric:
>> [...]
>>
>> /// @file
>>
>> /// My typedef.
>> typedef void VOID;
>>
>> /// My simple function. Details.
>> extern VOID Function(VOID);
>> [...]
[...]
> Agreed, at least when JAVADOC_AUTOBRIEF is specifically enabled it
> should work like that. But what I still don't understand, why does
> Doxygen then not emit warnings? Surely, having just a brief
> description does not also mean "and ignore parameters and return
> type"?

That might depend on whether you have "|WARN_IF_DOC_ERROR" and/or
"|||WARN_NO_PARAMDOC" |enabled. (Also, make sure you don't have
"EXTRACT_ALL" enabled.)|

> And why does the VOID redefine not work?

It appears that Doxygen's strategy for warning about undocumented
parameters or return types just doesn't expect anyone to ever typedef
any other type as "void", and thus doesn't bother to test whether the
return type and/or sole parameter's type is _equivalent_ with "void",
but rather just tests whether it _is_ "void".

This can be considered a bug, or it can be considered a feature: If you
do indeed want to indicate that your function does not return anything
at all, then why by all means do you not simply use the keyword "void"
(or leave the parameter list empty in case of C++)? On the other hand,
there might be cases where you may want some function to take or return
a parameter of a type that may or may not be configured to hold an
actual value (like, say, a type representing an error code, which may be
configured to be equivalent to "void" in an environment where other
means of error signalling, like throwing an exception, is used).  In
that case, you'd probably want Doxygen to warn you if you forget to
document that return value or parameter, even if it _may_ be configured
to be equivalent to "void" by default.

Re: [Doxygen-users] Two strange things about Doxygen and my code

[Bostjan M. <cco...@gm...>]

On Wed, Aug 26, 2015 at 2:41 PM, Christoph Lipka
<chr...@li...> wrote:
> Am 26.08.2015 um 11:14 schrieb Bostjan Mihoric:
>> On Tue, Aug 25, 2015 at 7:14 PM, Christoph Lipka
>> <chr...@li...> wrote:
>>> Am 25.08.2015 um 18:36 schrieb Bostjan Mihoric:
>>> [...]
>>>
>>> /// @file
>>>
>>> /// My typedef.
>>> typedef void VOID;
>>>
>>> /// My simple function. Details.
>>> extern VOID Function(VOID);
>>> [...]
> [...]
>> Agreed, at least when JAVADOC_AUTOBRIEF is specifically enabled it
>> should work like that. But what I still don't understand, why does
>> Doxygen then not emit warnings? Surely, having just a brief
>> description does not also mean "and ignore parameters and return
>> type"?
>
> That might depend on whether you have "|WARN_IF_DOC_ERROR" and/or
> "|||WARN_NO_PARAMDOC" |enabled. (Also, make sure you don't have
> "EXTRACT_ALL" enabled.)|
>

I have it exactly as you put it - all warnings are enabled (including
those two) and EXTRACT_ALL is disabled (NO).

>> And why does the VOID redefine not work?
>
> It appears that Doxygen's strategy for warning about undocumented
> parameters or return types just doesn't expect anyone to ever typedef
> any other type as "void", and thus doesn't bother to test whether the
> return type and/or sole parameter's type is _equivalent_ with "void",
> but rather just tests whether it _is_ "void".
>
> This can be considered a bug, or it can be considered a feature: If you
> do indeed want to indicate that your function does not return anything
> at all, then why by all means do you not simply use the keyword "void"
> (or leave the parameter list empty in case of C++)? On the other hand,
> there might be cases where you may want some function to take or return
> a parameter of a type that may or may not be configured to hold an
> actual value (like, say, a type representing an error code, which may be
> configured to be equivalent to "void" in an environment where other
> means of error signalling, like throwing an exception, is used).  In
> that case, you'd probably want Doxygen to warn you if you forget to
> document that return value or parameter, even if it _may_ be configured
> to be equivalent to "void" by default.
>

Yes, I agree that anything but "void" should be considered a different
type. What I meant is, why doesn't it work when I try to use Doxygen's
preprocessor to redefine "VOID" back  to "void". Surely it doesn't
preprocess *after* deciding if function has a return value /
parameters? If it's preprocessor replaced "VOID" with "void", why
doesn't it then see it as "void"?

>
> ------------------------------------------------------------------------------
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users

Re: [Doxygen-users] Two strange things about Doxygen and my code

[Dimitri v. H. <do...@gm...>]

Hi Bostjan,

>>> And why does the VOID redefine not work?
>> 
>> It appears that Doxygen's strategy for warning about undocumented
>> parameters or return types just doesn't expect anyone to ever typedef
>> any other type as "void", and thus doesn't bother to test whether the
>> return type and/or sole parameter's type is _equivalent_ with "void",
>> but rather just tests whether it _is_ "void".
>> 
>> This can be considered a bug, or it can be considered a feature: If you
>> do indeed want to indicate that your function does not return anything
>> at all, then why by all means do you not simply use the keyword "void"
>> (or leave the parameter list empty in case of C++)? On the other hand,
>> there might be cases where you may want some function to take or return
>> a parameter of a type that may or may not be configured to hold an
>> actual value (like, say, a type representing an error code, which may be
>> configured to be equivalent to "void" in an environment where other
>> means of error signalling, like throwing an exception, is used).  In
>> that case, you'd probably want Doxygen to warn you if you forget to
>> document that return value or parameter, even if it _may_ be configured
>> to be equivalent to "void" by default.
>> 
> 
> Yes, I agree that anything but "void" should be considered a different
> type. What I meant is, why doesn't it work when I try to use Doxygen's
> preprocessor to redefine "VOID" back  to "void". Surely it doesn't
> preprocess *after* deciding if function has a return value /
> parameters? If it's preprocessor replaced "VOID" with "void", why
> doesn't it then see it as "void"?

Did you check if the "VOID" macro is actually being replaced by "void", i.e.
by using -d preprocessor option and looking at the output? 
If it isn't then make sure also MACRO_EXPANSION is set to YES.

Regards,
  Dimitri

Re: [Doxygen-users] Two strange things about Doxygen and my code

[Bostjan M. <cco...@gm...>]

On Wed, Aug 26, 2015 at 3:56 PM, Dimitri van Heesch <do...@gm...> wrote:
> Hi Bostjan,
>
>>>> And why does the VOID redefine not work?
>>>
>>> It appears that Doxygen's strategy for warning about undocumented
>>> parameters or return types just doesn't expect anyone to ever typedef
>>> any other type as "void", and thus doesn't bother to test whether the
>>> return type and/or sole parameter's type is _equivalent_ with "void",
>>> but rather just tests whether it _is_ "void".
>>>
>>> This can be considered a bug, or it can be considered a feature: If you
>>> do indeed want to indicate that your function does not return anything
>>> at all, then why by all means do you not simply use the keyword "void"
>>> (or leave the parameter list empty in case of C++)? On the other hand,
>>> there might be cases where you may want some function to take or return
>>> a parameter of a type that may or may not be configured to hold an
>>> actual value (like, say, a type representing an error code, which may be
>>> configured to be equivalent to "void" in an environment where other
>>> means of error signalling, like throwing an exception, is used).  In
>>> that case, you'd probably want Doxygen to warn you if you forget to
>>> document that return value or parameter, even if it _may_ be configured
>>> to be equivalent to "void" by default.
>>>
>>
>> Yes, I agree that anything but "void" should be considered a different
>> type. What I meant is, why doesn't it work when I try to use Doxygen's
>> preprocessor to redefine "VOID" back  to "void". Surely it doesn't
>> preprocess *after* deciding if function has a return value /
>> parameters? If it's preprocessor replaced "VOID" with "void", why
>> doesn't it then see it as "void"?
>
> Did you check if the "VOID" macro is actually being replaced by "void", i.e.
> by using -d preprocessor option and looking at the output?
> If it isn't then make sure also MACRO_EXPANSION is set to YES.
>

Thank you for this. I went over whole config a couple of days ago, but
didn't remember that this should also be enabled. Now it replaced
correctly and there's no more warning.

As for the single line issue... it's not really a big deal, I'll just
be careful to doc everything and warnings won't be required.

Thanks again!

Re: [Doxygen-users] Two strange things about Doxygen and my code

[woody <kn...@re...>]

I have noticed some inconsistencies in the .rtf function.

Sometimes it puts the caller and called graph just after the name, and the 
code listing after that, and at other times it puts the caller and call 
graph AFTER the code listing.
as in

foo()

call graph

caller graph

       {
       gray box with code for foo in it
       }

OR

foo()
       {
       gray box with code for foo in it
       }

call graph

caller graph


I have also seen it NOT generate a caller graph, and call graph for a 
function that is clearly called multiple times from main.  That function 
does not call any, so I would expect the call graph to be blank, but
not the caller graph.....


I noticed that the call graph for main does not include calls made in 
conditionals.

For example
  if (dwell == 0)
     {
     control_function();
     }

control_function will not be referenced in the call diagram for main.

I am wondering what causes these?

I just used doxygen 1.8.x with it's default settings.  This is  code that 
does not have
any doxygen comments in it.

I have made extensive edits to the rtf file, so am not sure I want to try 
to re-generate it.

Re: [Doxygen-users] Two strange things about Doxygen and my code

[Christoph L. <chr...@li...>]

Am 26.08.2015 um 15:16 schrieb Bostjan Mihoric:
> On Wed, Aug 26, 2015 at 2:41 PM, Christoph Lipka
> <chr...@li...> wrote:
>> Am 26.08.2015 um 11:14 schrieb Bostjan Mihoric:
>>> On Tue, Aug 25, 2015 at 7:14 PM, Christoph Lipka
>>> <chr...@li...> wrote:
>>>> Am 25.08.2015 um 18:36 schrieb Bostjan Mihoric:
>>>> [...]
>>>>
>>>> /// @file
>>>>
>>>> /// My typedef.
>>>> typedef void VOID;
>>>>
>>>> /// My simple function. Details.
>>>> extern VOID Function(VOID);
>>>> [...]
[...]
> Yes, I agree that anything but "void" should be considered a different
> type. What I meant is, why doesn't it work when I try to use Doxygen's
> preprocessor to redefine "VOID" back  to "void". Surely it doesn't
> preprocess *after* deciding if function has a return value /
> parameters? If it's preprocessor replaced "VOID" with "void", why
> doesn't it then see it as "void"?

Did you set "MACRO_EXPANSION = YES"? The default value of "No" causes
Doxygen's preprocessor to only do conditional compilation.

Re: [Doxygen-users] Two strange things about Doxygen and my code

[Bostjan M. <cco...@gm...>]

On Sun, Aug 30, 2015 at 12:54 AM, Christoph Lipka
<chr...@li...> wrote:
> Am 26.08.2015 um 15:16 schrieb Bostjan Mihoric:
>
> On Wed, Aug 26, 2015 at 2:41 PM, Christoph Lipka
> <chr...@li...> wrote:
>
> Am 26.08.2015 um 11:14 schrieb Bostjan Mihoric:
>
> On Tue, Aug 25, 2015 at 7:14 PM, Christoph Lipka
> <chr...@li...> wrote:
>
> Am 25.08.2015 um 18:36 schrieb Bostjan Mihoric:
> [...]
>
> /// @file
>
> /// My typedef.
> typedef void VOID;
>
> /// My simple function. Details.
> extern VOID Function(VOID);
> [...]
>
> [...]
>
> Yes, I agree that anything but "void" should be considered a different
> type. What I meant is, why doesn't it work when I try to use Doxygen's
> preprocessor to redefine "VOID" back  to "void". Surely it doesn't
> preprocess *after* deciding if function has a return value /
> parameters? If it's preprocessor replaced "VOID" with "void", why
> doesn't it then see it as "void"?
>
>
> Did you set "MACRO_EXPANSION = YES"? The default value of "No" causes
> Doxygen's preprocessor to only do conditional compilation.
>

Yes, resolved by this. Thank you!