doxygen-users — List for users of doxygen

Re: [Doxygen-users] erroneous output of section label for \cond command

[Albert <alb...@gm...>]

Monique,

I'm not aware of a bug in this respect. Can you post a small example with
the Doxyfile used (to generated the Doxyfile please use doxygen -s so it is
a bit smaller).

Albert

On Thu, Aug 27, 2015 at 6:43 PM, Monique Semp <mon...@ea...>
wrote:

> Hello, doxygen-users,
>
> I’m using Doxygen 1.8.10, on Mac 10.10.3 (Yosemite).
>
> I’ve used the \cond and \endcond tags to omit documentation for some class
> members, via a section label of the sort
> __INCLUDE_DOXYGEN_FOR_THESE_DEFINES__. (And of course, I’m not defining
> these labels in the ENABLED_SECTIONS part of the Doxyfile.)
>
> The output correctly omits the members that are between the \cond and
> \endcond commands, but... the section label itself
> (“__INCLUDE_DOXYGEN_FOR_THESE_DEFINES__”) is appearing in the output, in
> bold on its own line, in the detailed output for the next documented member
> in the file. This erroneous output appears before the text of the \details
> command.
>
> Is there perhaps some configuration setting that I need to set to suppress
> this unexpected output?
>
> Thanks,
> -Monique
>
>
> ------------------------------------------------------------------------------
>
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>
>

[Doxygen-users] erroneous output of section label for \cond command

[Monique S. <mon...@ea...>]

Hello, doxygen-users,

I’m using Doxygen 1.8.10, on Mac 10.10.3 (Yosemite).

I’ve used the \cond and \endcond tags to omit documentation for some class members, via a section label of the sort __INCLUDE_DOXYGEN_FOR_THESE_DEFINES__. (And of course, I’m not defining these labels in the ENABLED_SECTIONS part of the Doxyfile.)

The output correctly omits the members that are between the \cond and \endcond commands, but... the section label itself (“__INCLUDE_DOXYGEN_FOR_THESE_DEFINES__”) is appearing in the output, in bold on its own line, in the detailed output for the next documented member in the file. This erroneous output appears before the text of the \details command.

Is there perhaps some configuration setting that I need to set to suppress this unexpected output?

Thanks,
-Monique

Re: [Doxygen-users] Doxygen warnings on macros

[Albert <alb...@gm...>]

Hi Sai,

I think in the comment you have some code with #ifndef, the # implies that
a link should be generated. There are a number of possibilities:
- use: \#ifndef
- use #‌ifndef

If this does not solve your case please create a small example.

Albert

On Thu, Aug 27, 2015 at 7:51 AM, sai mrithyunjaya <ts...@gm...> wrote:

> Hi All,
>
> We have been trying to run a doxygen config file (1.8.10) and got a
> warning saying that "warning : explicit link request to 'ifndef' could not
> be resolved".
>
> Same case with #define too.
>
> So could anyone help us to find a way to  to remove such type of warnings.
>
> Thanks in advance.
>
> Thank you
> Sai
>
>
> ------------------------------------------------------------------------------
>
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>
>

[Doxygen-users] Doxygen warnings on macros

[sai m. <ts...@gm...>]

Hi All,

We have been trying to run a doxygen config file (1.8.10) and got a warning
saying that "warning : explicit link request to 'ifndef' could not be
resolved".

Same case with #define too.

So could anyone help us to find a way to  to remove such type of warnings.

Thanks in advance.

Thank you
Sai

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.

[Doxygen-users] Doxygen Qt Help

[Suseelan, K. R. B. <Kum...@fs...>]

Hi,

This may be more close to doxygen setup.

I have used doxygen documentation format and I am able to generate the documentation successfully.

Question is that,
My class is derived from QPushButton.

[cid:image001.png@01D0E024.3F467150]

In the class diagram, I would like to click on QPushButton and see where it is derived from.
But please note that, QPushButton is a Qt class.

How do I achieve this?

Thank you,
Kumara

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] warning at explicit instantiation of overloaded template class member function

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

Hi Harald,

> On 26 Aug 2015, at 16:32 , Heese, Harald <har...@ph...> wrote:
> 
> Hi Dimitri!
> 
> Thanks for the quick answer.
> 
> You are right, the provided code does not compile. The modified example now is
> 
> //! a test class with overloaded template members
> class Bar
> {
> public:
>  //! first overload of template member function
>  template <typename T>
>  T foo(T a, int b)
>  { return a; }
> 
>  //! second overload of template member function
>  template <typename T>
>  T foo(T a, double c)
>  { return a; }
> };
> 
> //! force instantiation of first overload for type 'short'
> template short Bar::foo<short>(short, int);
> 
> If you compile this using
> gcc -c bar.cpp
> 
> the corresponding object file will contain exactly one symbol (which you can see using nm). This is exactly what is intended (to force the creation of a symbol for a specific template parameter).
> 
> The syntax you suggested refers to a different concept, namely "template specialization". In that case, the statement
>  template<> short Bar::foo<short>(short, int);
> is a function declaration, which would require a separate function definition in order to create a corresponding symbol. If I would compile the modified example with your suggestion, then the corresponding object file does not contain any symbols (which is not what is intended).

I see. A solution/workaround is to use \relates, i.e.:

//! \relates Bar
//! \brief force instantiation of first overload for type 'short'
template short Bar::foo<short>(short, int);

Regards,
  Dimitri

Re: [Doxygen-users] warning at explicit instantiation of overloaded template class member function

[Heese, H. <har...@ph...>]

Hi Dimitri!

Thanks for the quick answer.

You are right, the provided code does not compile. The modified example now is

//! a test class with overloaded template members
class Bar
{
public:
  //! first overload of template member function
  template <typename T>
  T foo(T a, int b)
  { return a; }

  //! second overload of template member function
  template <typename T>
  T foo(T a, double c)
  { return a; }
};

//! force instantiation of first overload for type 'short'
template short Bar::foo<short>(short, int);

If you compile this using
gcc -c bar.cpp

the corresponding object file will contain exactly one symbol (which you can see using nm). This is exactly what is intended (to force the creation of a symbol for a specific template parameter).

The syntax you suggested refers to a different concept, namely "template specialization". In that case, the statement
  template<> short Bar::foo<short>(short, int);
is a function declaration, which would require a separate function definition in order to create a corresponding symbol. If I would compile the modified example with your suggestion, then the corresponding object file does not contain any symbols (which is not what is intended).

Best regards,
Harald


-----Original Message-----
From: Dimitri van Heesch [mailto:do...@gm...]
Sent: Wednesday, August 26, 2015 4:04 PM
To: Heese, Harald
Cc: dox...@li...
Subject: Re: [Doxygen-users] warning at explicit instantiation of overloaded template class member function

Hi Harald,

> On 26 Aug 2015, at 15:19 , Heese, Harald <har...@ph...> wrote:
>
> Hi doxygen,
>
> I am encountering warnings using Doxygen 1.8.10 for the below example of overloaded template member functions with explicit instantiation of one (or more) of the overloads for specific template types.
>
> //! a test class with overloaded template members class Bar {
> public:
>  //! first overload of template member function  template <typename T>
> T foo(T a, int b);
>
>  //! second overload of template member function  template <typename
> T>  T foo(T a, double c); };
>
> //! force instantiation of first overload for type 'short'
> template short Bar::foo<short>(short, int);
>
> Output
>
> warning: no matching class member found for  template short Bar::foo<
> short >(short, int) Possible candidates:
>  'template < T >
>  T Bar::foo(T a, int b)
>  'template < T >
>  T Bar::foo(T a, double c)
>
> Is there a way to incorporate the existence of an explicit instantiation (or its accompanying doxygen documentation) in the detailed documentation of the class member (which happens if there are no overloads)?

If you use

//! force instantiation of first overload for type 'short'
template<> short Bar::foo<short>(short, int);

it should work. Note the <> after template. My compiler doesn't even compile the code without it.

Groeten,
  Dimitri


________________________________
The information contained in this message may be confidential and legally protected under applicable law. The message is intended solely for the addressee(s). If you are not the intended recipient, you are hereby notified that any use, forwarding, dissemination, or reproduction of this message is strictly prohibited and may be unlawful. If you are not the intended recipient, please contact the sender by return e-mail and destroy all copies of the original message.

Re: [Doxygen-users] warning at explicit instantiation of overloaded template class member function

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

Hi Harald,

> On 26 Aug 2015, at 15:19 , Heese, Harald <har...@ph...> wrote:
> 
> Hi doxygen,
> 
> I am encountering warnings using Doxygen 1.8.10 for the below example of overloaded template member functions with explicit instantiation of one (or more) of the overloads for specific template types.
> 
> //! a test class with overloaded template members
> class Bar
> {
> public:
>  //! first overload of template member function
>  template <typename T>
>  T foo(T a, int b);
> 
>  //! second overload of template member function
>  template <typename T>
>  T foo(T a, double c);
> };
> 
> //! force instantiation of first overload for type 'short'
> template short Bar::foo<short>(short, int);
> 
> Output
> 
> warning: no matching class member found for
>  template short Bar::foo< short >(short, int)
> Possible candidates:
>  'template < T >
>  T Bar::foo(T a, int b)
>  'template < T >
>  T Bar::foo(T a, double c)
> 
> Is there a way to incorporate the existence of an explicit instantiation (or its accompanying doxygen documentation) in the detailed documentation of the class member (which happens if there are no overloads)?

If you use

//! force instantiation of first overload for type 'short'
template<> short Bar::foo<short>(short, int);

it should work. Note the <> after template. My compiler doesn't even compile the code without it.

Groeten,
  Dimitri

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

[Doxygen-users] warning at explicit instantiation of overloaded template class member function

[Heese, H. <har...@ph...>]

Hi doxygen,

I am encountering warnings using Doxygen 1.8.10 for the below example of overloaded template member functions with explicit instantiation of one (or more) of the overloads for specific template types.

//! a test class with overloaded template members
class Bar
{
public:
  //! first overload of template member function
  template <typename T>
  T foo(T a, int b);

  //! second overload of template member function
  template <typename T>
  T foo(T a, double c);
};

//! force instantiation of first overload for type 'short'
template short Bar::foo<short>(short, int);

Output

warning: no matching class member found for
  template short Bar::foo< short >(short, int)
Possible candidates:
  'template < T >
  T Bar::foo(T a, int b)
  'template < T >
  T Bar::foo(T a, double c)

Is there a way to incorporate the existence of an explicit instantiation (or its accompanying doxygen documentation) in the detailed documentation of the class member (which happens if there are no overloads)?

Thanks,
Harald Heese



________________________________
The information contained in this message may be confidential and legally protected under applicable law. The message is intended solely for the addressee(s). If you are not the intended recipient, you are hereby notified that any use, forwarding, dissemination, or reproduction of this message is strictly prohibited and may be unlawful. If you are not the intended recipient, please contact the sender by return e-mail and destroy all copies of the original message.

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

[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 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 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.)

[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

[Doxygen-users] How to do a Typedef tag for a forward declared macro

[didje <dia...@pd...>]

Typedef tag for a forward declared macro does not work

Doxygen 1.8.10

The following properties are set in the Doxyfile

ENABLE_PREPROCESSING   = YES
MACRO_EXPANSION        = YES
EXPAND_ONLY_PREDEF     = YES
EXPAND_AS_DEFINED      = FWD_DECL_SHD_PTR

In a test.dox.cpp file, I have the following:

namespace abc {
namespace def {
/*! \typedef boost::shared_ptr<FileRecord> FileRecord_ptr
* A shared pointer of a FileRecord 
*/
}
}

In a test.h file, I have the following macro:

FWD_DECL_SHD_PTR(FileRecord);

Here it the definiton of that macro:

#define FWD_DECL_SHD_PTR(T)

The macro forward declares a shared pointer to T of the form {{T}}_ptr

Therefore, in the above case, it forward declares a shared pointer named
FileRecord_ptr

However, when I generate the documentation, I see the following warning:

warning: documented symbol `boost::shared_ptr< FileRecord > FileRecord_ptr'
was not declared or defined.



--
View this message in context: http://doxygen.10944.n7.nabble.com/How-to-do-a-Typedef-tag-for-a-forward-declared-macro-tp7329.html
Sent from the Doxygen - Users mailing list archive at Nabble.com.

[Doxygen-users] modularization of Doxygen language processing

[Clayton <cla...@gm...>]

Hi guys,

We are evaluating Doxygen as a possible engine for large-scale analysis
of GitHub projects, and as such, are interested in analyzing languages
in addition to the list of languages that core Doxygen currently
processes. We are aware of Doxygen's ability to pull in separate
language-specific "plugin" scripts via the FILTER_PATTERNS setting, but
are thinking of something more tightly integrated into doxygen. (Many
of these scripts are very slow, for instance....)

I ran across this in the Doxygen documention:

	http://www.stack.nl/~dimitri/doxygen/manual/arch.html

	"Possible improvements for future versions: Use one
	scanner/parser per language instead of one big scanner."

Has any thought / analysis / work gone into this? Is it perceived as a
huge task, or just something no one has gotten around to yet?

TIA for your thoughts,
Clayton

Re: [Doxygen-users] FILE_PATTERNS: one custom plus all defaults

[Clayton <cla...@gm...>]

Hi Albert, I just built your pull request

	https://github.com/doxygen/doxygen/pull/383

from source and tested it on a hundred+ github javascript repositories,
it works as expected: lots of javascript output. We would really like to
see this patch merged into master. 

Plus, the current master quite likely gives many people the impression
that doxygen processing of javascript is broken, which it is not.

Thanks for writing the fix,
Clayton

On Mon, 17 Aug 2015 18:44:48 +0200
Albert <alb...@gm...> wrote:

> Bug report is not really needed.
> 
> I don't think the other places are in conflict.
> There is no separate javascript parser but it is more or less
> integrated in the c parser. The g_lang2extMap tells that javascript
> type of files have to be parsed by the c parser and that the type of
> language is SrcLangExt_JS. With the later it is possible to ask in
> the code which language a file has and do special things for this
> language.
> 
> The initDefaultExtensionMapping maps the files extension to the
> language type of files.
> 
> Albert
> 
> 
> 
> 
> On Mon, Aug 17, 2015 at 10:09 AM, Clayton <cla...@gm...> wrote:
> 
> > Thanks for the quick work, Albert. Does this mean a bug report is
> > now no longer needed? (That's quite the list of bugs in
> > Bugzilla....)
> >
> > It looks to me like your patch leaves js in. And I am in fact
> > seeing at least two different references in util.cpp, which also
> > might be in conflict:
> >
> > g_lang2extMap[] =
> > {
> > //  language       parser           parser option
> >   { "javascript",  "c",             SrcLangExt_JS       },
> >
> >
> > void initDefaultExtensionMapping()
> > {
> >   g_extLookup.setAutoDelete(TRUE);
> >   //                  extension      parser id
> >   updateLanguageMapping(".as",       "javascript");
> >   updateLanguageMapping(".js",       "javascript");
> >
> > The second reference above gives the impression that there is an
> > internal doxygen parser for javascript? Really??
> >
> > Clayton
> >
> >
> >
> >
> > On Sun, 16 Aug 2015 18:21:46 +0200
> > Albert <alb...@gm...> wrote:
> >
> > > I've just pushed a proposed patch to github (pull request 383)
> > >
> > > Albert
> > >
> > > On Sun, Aug 16, 2015 at 4:06 PM, Albert <alb...@gm...>
> > > wrote:
> > >
> > > > The following does not yet solve your problem, but points in the
> > > > direction where we have to look to solve the problem:
> > > > There is in util.cpp another list which does contain .js, looks
> > > > like a small inconsistency between config.xml, util.cpp and
> > > > config.l. Please file a bug report to signal this discrepancy.
> > > >
> > > > Albert
> > > >
> > > >
> > > > On Sun, Aug 16, 2015 at 3:09 PM, Clayton <cla...@gm...>
> > > > wrote:
> > > >
> > > >> On Sun, 16 Aug 2015 14:05:56 +0200
> > > >> Stefan Pendl <ste...@gm...> wrote:
> > > >>
> > > >> > Am 16.08.2015 um 13:45 schrieb Clayton:
> > > >> > > Hi doxygen,
> > > >> > >
> > > >> > > I am looking at the config file and writing to ask if I am
> > > >> > > missing something.
> > > >> > >
> > > >> > > I am using
> > > >> > >
> > > >> > >     FILE_PATTERNS = *.js
> > > >> > >     FILTER_PATTERNS = *.js=plugins/js2doxy/js2doxy.pl
> > > >> >
> > > >> > From the help file topic "Configuration => Configuration
> > > >> > options related to the input files => FILE_PATTERNS" it
> > > >> > seems that *.js is included in the default already.
> > > >> >
> > > >> > Is your doxygen version less than v1.8.10?
> > > >>
> > > >> Hi Stefan, the help is not the same as the code, from
> > > >> src/config.l in a very recent clone of the source, I believe
> > > >> this to be the ACTUAL default list of file patterns:
> > > >>
> > > >>   QStrList &filePatternList = Config_getList("FILE_PATTERNS");
> > > >>   if (filePatternList.isEmpty())
> > > >>   {
> > > >>     filePatternList.append("*.c");
> > > >>     filePatternList.append("*.cc");
> > > >>     filePatternList.append("*.cxx");
> > > >>     filePatternList.append("*.cpp");
> > > >>     filePatternList.append("*.c++");
> > > >>     filePatternList.append("*.java");
> > > >>     filePatternList.append("*.ii");
> > > >>     filePatternList.append("*.ixx");
> > > >>     filePatternList.append("*.ipp");
> > > >>     filePatternList.append("*.i++");
> > > >>     filePatternList.append("*.inl");
> > > >>     filePatternList.append("*.h");
> > > >>     filePatternList.append("*.hh");
> > > >>     filePatternList.append("*.hxx");
> > > >>     filePatternList.append("*.hpp");
> > > >>     filePatternList.append("*.h++");
> > > >>     filePatternList.append("*.idl");
> > > >>     filePatternList.append("*.odl");
> > > >>     filePatternList.append("*.cs");
> > > >>     filePatternList.append("*.php");
> > > >>     filePatternList.append("*.php3");
> > > >>     filePatternList.append("*.inc");
> > > >>     filePatternList.append("*.m");
> > > >>     filePatternList.append("*.mm");
> > > >>     filePatternList.append("*.dox");
> > > >>     filePatternList.append("*.py");
> > > >>     filePatternList.append("*.f90");
> > > >>     filePatternList.append("*.f");
> > > >>     filePatternList.append("*.for");
> > > >>     filePatternList.append("*.vhd");
> > > >>     filePatternList.append("*.vhdl");
> > > >>     filePatternList.append("*.tcl");
> > > >>     filePatternList.append("*.md");
> > > >>     filePatternList.append("*.markdown");
> > > >>
> > > >> *.js is not in there. The plugin is necessary, the point is,
> > > >> how to get the plugin to integrate with the default list
> > > >> automatically, without explicitly adding the default list to
> > > >> FILE_PATTERNS.
> > > >>
> > > >> Thanks,
> > > >> Clayton
> > > >>
> > > >>
> > > >>
> > ------------------------------------------------------------------------------
> > > >> _______________________________________________
> > > >> Doxygen-users mailing list
> > > >> Dox...@li...
> > > >> https://lists.sourceforge.net/lists/listinfo/doxygen-users
> > > >>
> > > >
> > > >
> >
> >
> > ------------------------------------------------------------------------------
> > _______________________________________________
> > Doxygen-users mailing list
> > Dox...@li...
> > https://lists.sourceforge.net/lists/listinfo/doxygen-users
> >

Re: [Doxygen-users] suppress title/lead-in for multiple instances of (aliased) custom commands for \par ?

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

If you can do without the introductory text ("To enable this function,
the following preprocessor directives must be defined"), the \xrefitem
command may be the way to go:

ALIASES = preprocess=”\xrefitem preprocess \"Required Preprocessor
Directives\" \"Conditional Compilation\" \n+ \c“

Note that this has the side effect of generating an additional page with
all of the conditional compilation stuff (titled "Conditional
Compilation" in the above example), like you get with the "\todo"
command; this may or may not be considered a benefit.


Am 19.08.2015 um 22:15 schrieb Monique Semp:
> Hello, Doxygen users,
>  
> I’m using Doxygen 1.8.10 on Mac OS X 10.10.3 (Yosemite).
>  
> Summary:
>  
> I created an alias to use for listing preprocessor directives that are
> required to be defined in order to enable the function that’s being
> documented. The alias is to the \par command so that I can have a
> custom heading and lead-in paragraph, and then the specified compiler
> directive. This all works great when there’s only a single directive
> required for a function, but when there are multiple directives, I
> haven’t figured out how to consolidate the output into a single
> heading/intro text/list.
>  
> Details:
>  
> Here’s the code I added to the Doxyfile:
>  
> ALIASES = preprocess=”\par Preprocessor Directives\nTo enable this
> function, the following preprocessor directives must be defined:\n+ \c “
>  
> This works wonderfully when I have just a single directive specified
> in the function’s comment block as “@preprocess __FLAG1__”. The output
> is a bold heading, “Preprocessor Directives”, then the explanation on
> the next line, and finally the __FLAG1__ listed in code font as a
> bullet point.
>  
> But... If if use a 2nd @preprocess command in a single function’s
> comments, the 2nd flag has the heading and intro text again. And of
> course what I want is a single heading/intro and then a consolidated
> list of the all the function’s @preprocess flags.
>  
> I’ve tried adding the \parblock, \endparblock commands to the function
> comment block, but that didn’t have any effect. Perhaps I could do
> this by overloading the @preprocess command with aliases defined for
> 1, 2, 3, etc. arguments. But I’d eventually be stuck, I’m sure, with a
> function that requires more flags than however many arguments I’d defined.
>  
> Any suggestions as to how to implement this?
>  
> Thanks very much,
> -Monique
>  
>
>
> ------------------------------------------------------------------------------
>
>
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users

Re: [Doxygen-users] doxywizard can't run PlantUML

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

Sorry the code got truncated; I should probably have posted directly to
the list.
Here's the code again:

------------------------------------------------

:JAVA_SYMLINK_FIX

rem set JAVA_EXE to whatever java.exe is found via the path
call :FIND_IN_PATH JAVA_EXE java.exe
rem set TRUE_JAVA_EXE to the actual file java.exe points to (if it is a
rem symlink), or an empty string otherwise
call :FIND_SYMLINK TRUE_JAVA_EXE "%JAVA_EXE%"
rem if the java.exe found via the path is not a symlink, we're done
if "%TRUE_JAVA_EXE%" == "" goto :EOF
echo "%JAVA_EXE%" is a symlink pointing to "%TRUE_JAVA_EXE%"
rem set JAVA_EXE_DIR to the directory in which the actual java.exe resides
call :SET_DIR JAVA_EXE_DIR "%TRUE_JAVA_EXE%"
rem prepend JAVA_EXE_DIR to the path variable
set PATH=%JAVA_EXE_DIR%;%PATH%
 goto :EOF

:FIND_IN_PATH
set %1=%~dp$PATH:2%2
goto :EOF

:FIND_SYMLINK
rem Sets the environment variable named by %1 to the file pointed to by %2
rem if that's a symlink.Sets the environment variable to an empty string
rem otherwise.
set %1=
for /F "usebackq tokens=2 delims=[]" %%i in (`dir "%~2" /N`) do set %1=%%i
goto :EOF

:SET_DIR
rem Sets the environment variable named by %1 to the directory of the file
rem named by %2.
set %1=%~dp2
goto :EOF


------------------------------------------------

Am 20.08.2015 um 05:15 schrieb Christoph Lipka:
> In the batch file I'm using to run Doxygen, I've now added the following
> subroutine to get around the problem:
>
> ------------------------------
>
> ------------------------------
>
> If you need to use doxywizard to actually run Doxygen (as opposed to just
> generating a config file for it), you could launch doxywizard via a batch
> file, using the very same code snippet; as far as I know that should do the
> job as well.
>
>
>
> --
> View this message in context: http://doxygen.10944.n7.nabble.com/doxywizard-can-t-run-PlantUML-tp7188p7324.html
> Sent from the Doxygen - Users mailing list archive at Nabble.com.
>
> ------------------------------------------------------------------------------
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>

Re: [Doxygen-users] doxywizard can't run PlantUML

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

In the batch file I'm using to run Doxygen, I've now added the following
subroutine to get around the problem:

------------------------------

------------------------------

If you need to use doxywizard to actually run Doxygen (as opposed to just
generating a config file for it), you could launch doxywizard via a batch
file, using the very same code snippet; as far as I know that should do the
job as well.



--
View this message in context: http://doxygen.10944.n7.nabble.com/doxywizard-can-t-run-PlantUML-tp7188p7324.html
Sent from the Doxygen - Users mailing list archive at Nabble.com.

[Doxygen-users] suppress title/lead-in for multiple instances of (aliased) custom commands for \par ?

[Monique S. <mon...@ea...>]

Hello, Doxygen users,

I’m using Doxygen 1.8.10 on Mac OS X 10.10.3 (Yosemite).

Summary:

I created an alias to use for listing preprocessor directives that are required to be defined in order to enable the function that’s being documented. The alias is to the \par command so that I can have a custom heading and lead-in paragraph, and then the specified compiler directive. This all works great when there’s only a single directive required for a function, but when there are multiple directives, I haven’t figured out how to consolidate the output into a single heading/intro text/list.

Details:

Here’s the code I added to the Doxyfile:

ALIASES = preprocess=”\par Preprocessor Directives\nTo enable this function, the following preprocessor directives must be defined:\n+ \c “

This works wonderfully when I have just a single directive specified in the function’s comment block as “@preprocess __FLAG1__”. The output is a bold heading, “Preprocessor Directives”, then the explanation on the next line, and finally the __FLAG1__ listed in code font as a bullet point.

But... If if use a 2nd @preprocess command in a single function’s comments, the 2nd flag has the heading and intro text again. And of course what I want is a single heading/intro and then a consolidated list of the all the function’s @preprocess flags.

I’ve tried adding the \parblock, \endparblock commands to the function comment block, but that didn’t have any effect. Perhaps I could do this by overloading the @preprocess command with aliases defined for 1, 2, 3, etc. arguments. But I’d eventually be stuck, I’m sure, with a function that requires more flags than however many arguments I’d defined.

Any suggestions as to how to implement this?

Thanks very much,
-Monique

Re: [Doxygen-users] fenced code block bug

[Paul A. L. <pa...@le...>]

Hi again.

Well, this is embarrassing, but as expected in a way - when creating a minimal working example, the problem showed itself. It turns out someone had subtly modified the DoxyCode environment in the document preamble, by using verbatim instead of typewriter font. This caused the LaTeX commands to shine through into the generated PDF.

Thanks for all your help!

Paul

> On 17. aug. 2015, at 19.33, Albert <alb...@gm...> wrote:
> 
> Which LaTeX version are you using on your system. There are problems with some a bit older LaTeX versions. Might be good to have a look at the recent texlive version (solved a lot of problems for me on Linux).
> 
> I used your code, incorporated as follows in a file aa.h:
> /** \file
> ~~~
> 'THIS IS A COMMENT
> 'NOTE! COMMENTS ARE IGNORED BY THE PROGRAM
> ~~~
> */
> 
> I used a default Doxyfile, but don't see the line numbers (I've seen remarks about this before, but I don't remember under which circumstances).
> Maybe you can attach a small complete example (source and Doxyfile, with the Doxyfile when generating it use the -s option and try to pack it in a zip file as attachments are limited in size).
> 
> 
> Regarding the \- \+ I think they will be there for a good reason (The change from \- to \+ was commented as follows: Use hook arrow for hyphens in symbol names in the LaTeX output.).
> 
> Albert
> 
> On Mon, Aug 17, 2015 at 9:22 AM, Paul Anton Letnes <pa...@le...> wrote:
> Hi!
> 
> Okay, so I've dug further into the matter. doxygen 1.8.5 (centos 7) and 1.8.6 (ubuntu 14.04) creates this LaTeX code:
>   0  \begin{DoxyCode}
>   1 \textcolor{stringliteral}{'THIS IS A COMMENT}
>   2 \textcolor{stringliteral}{'}NOTE! COMMENTS ARE IGNORED BY THE PROGRAM
>   3 \end{DoxyCode}
> whereas 1.8.9.1 (cygwin, not sure when it was updated last) creates this LaTeX code:
>   0  \begin{DoxyCode}
>   1 1 'THIS IS A COMMENT
>   2 2 'NOTE! COMMENTS ARE IGNORED BY THE PROGRAM
>   3 \end{DoxyCode}
> 
> Notably, line numbering is suddenly enabled. I've got my markdown sources in git, btw, so they should be identical. The 1.8.[56] LaTeX code compiles on the LaTeX versions on their respective OS-es, but gives the screenshot attached: The \textcolor{...} stuff is included in the output, which it should not be.
> 
> On cygwin LaTeX and doxygen 1.8.9.1, the LaTeX does not compile due to another change in the generated LaTeX - there's a lot of \+ commands in CAPITALIZED words (can this be disabled?). On 1.8.[56], there are \- commands. For example:
> 
> Markdown:
> CAPITALIZED
> LaTeX from 1.8.[56]:
> C\-A\-P\-I\-T\-A\-L\-I\-Z\-E\-D
> LaTeX from 1.8.9.1:
> C\+A\+P\+I\+T\+A\+L\+I\+Z\+E\+D
> 
> Is it possible to disable the backslash plusminus behavior? And why do we see the differences in generated DoxyCode blocks? The version change 1.8.5 to 1.8.9 is a fairly minor one, so I'm a bit surprised. Any advice greatly appreciated.
> 
> -----------
> Paul Anton
> 
> 
> Den 14. august 2015 skrev woody <kn...@re...>:
> 
> Given that curly braces enclose items, it is 
> Pretty clear that the {'}  is a stand alone quote, and the remainder of the line NOTE!.... is just a line of text, and passed through directly to the output.
> However, if the code was
> {'NOTE!.......}        
> then I assume it will behave correctly.  perhaps reformatting it so the braces line up properly will reveal this.
> 
> ~~~
> 
> 'THIS IS A COMMENT
> 
> 'NOTE! COMMENTS ARE IGNORED BY THE PROGRAM 
> ~~~ 
> the resulting LaTeX code has errors in it (the HTML looks fine): 
> \begin
> 
>                 {
>                 DoxyCode
>                 }
> \textcolor 
>         { 
>           stringliteral 
>         }
> {'THIS IS A COMMENT}
> \textcolor 
>        { 
>        stringliteral 
>         }
>       {'} 
>         NOTE! COMMENTS ARE IGNORED BY THE PROGRAM 
> \end{DoxyCode}
> 
> This leads to the \textcolor command passing through to the PDF document. Also, the curly brace looks off in the second line.
> 
> Are there any fixes in more recent versions of doxygen? Or is there a workaround that's not too bad? Sometimes it helps to give the .m suffix, e.g. ~~~{.m}, to the code block - but weirdly, not always.
> 
> ----------- 
> Paul Anton
> 
> ------------------------------------------------------------------------------
> 
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users