doxygen-users — List for users of doxygen

[Doxygen-users] How do I use HTML tags and styling in \mainpage title

[dgarlisch <dav...@gm...>]

I want to use dox command and html tags and css styling in the title value
for *\mainpage [(title)]*. For example;

\mainpage <a href="http://www.pointwise.com/plugins">Pointwise Plugin
SDK</a> <span id='version'>v\htmlinclude
version.txt</span>

Where, /version.txt/ contains a string similar to /0100r11/. I have custom
CSS that floats the <span> to the right edge. The /version.txt/ file
is used by other automated processes. I want to use it here to make sure the
dox output and the automated processes stay in sync.

All works great in the browser page itself. However, I discovered this text
is also used as-is (without substitutions) for the browser page
<title> and is displayed in the tab's popup tooltip. This produces
undesirable results:

<http://doxygen.10944.n7.nabble.com/file/t2027/pluginsdk-mainpage.png> 

I have searched both google the existing forum posts and cannot find a
solution.

Is there a way to make this work or do I need to remove the html tags from
the text?

Is there a way to set the &lt;title&gt; text value that over-rides the
\mainpage title value?

Thanks,
David




--
Sent from: http://doxygen.10944.n7.nabble.com/Doxygen-Users-f3.html

[Doxygen-users] Markdown not working within \includedoc

[Greg E. <er...@se...>]

    Hi all, another question.

    I have several C++ classes that need a common page or two of documentation
    for each, and am exploring consolidating that content into a single .dox file,
    and using \includedoc to pull it in, e.g.

///
/// Class description goes here.
///
/// \includedoc test.dox
///

    But when I do this, some of the markdown in test.dox is not being handled
    correctly (see screenshots below).

    Here's an /exact/ paste of what I have in test.dox:

_________________________________________________________ snip
This content is in test.dox. Here's some bullet points:

  - One
  - Two

Header Number 1
===============
Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Header Number 2
---------------
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Here's a table:

Color    | Description
-------- | -----------
Red      | Component side
Green    | Solder side

This is the end of test.dox
_________________________________________________________ snip

    If I paste that content directly into a doxygen comment
    (without \includedoc) it looks as I'd expect:
    http://seriss.com/people/erco/tmp/doxygen-includedoc-good.png

    But if I use \includedoc on the same content, it looks like this:
    http://seriss.com/people/erco/tmp/doxygen-includedoc-bad.png

    Note bullets look OK, but headers and table are stretched out
    as if the markdown wasn't supported, as regular text content.

    Can't think what I'm missing here, especially since the bullets
    look OK. Shouldn't the markdown work inside \includedoc?

Re: [Doxygen-users] Make server side search work

[Fabian C. <Cen...@in...>]

At 09:47 09.05.2018, you wrote:
>Hi
>
>We put the doxygen generated documentation on a server and used
>the client side search previously. However some words could not be
>found as the client side search is not a full text search. That's why
>we now wanted to switch to server side search to get better results.
>
>The server is a linux with Apache with php, we also have e.g. MantisBT
>(bugtracker) and DocuWiki running on the same server, so php (7) is
>running fine. The documentation is generated on a different computer
>and then the whole html directory (output from doxygen) is copied
>to the live server.
>
>But when I try to search for something no results are returned, just
>like in this question:
>
>https://stackoverflow.com/questions/48440476/doxygen-server-side-searching-does-not-work
>
>These are the options from my Doxyfile:
>
>SEARCHENGINE           = YES
>SERVER_BASED_SEARCH    = YES
>EXTERNAL_SEARCH        = NO
>SEARCHENGINE_URL       =
>SEARCHDATA_FILE        = searchdata.xml
>
>In the html/search directory is a search.idx file with all the text strings.
>I don't see errors in the logfiles in /var/log/.
>
>Is something else needed? Is there some debugging I can enable?

Still trying to make this work. Has anybody used this?
Should this work with PHP7?

Thanks

bye  Fabi

Re: [Doxygen-users] doxygen commenting with //!< not working for last parameter of C++ methods

[Robert H. <he...@de...>]

At Sat, 12 May 2018 23:05:03 -0700 Greg Ercolano <er...@se...> wrote:

> 
> On 05/12/18 08:47, Richard Damon wrote:
> > On 5/11/18 2:44 PM, Greg Ercolano wrote:
> >>
> >>     I'd like to use //!< to comment the function/method parameters,
> >>     but the coding style of the project seems to be causing trouble
> >>     when it's used on the last argument:
> >>
> >> __________________________________________________________________ snip
> >> [..]
> >> string AskApp(const char *cmd,          //!< command to send app
> >>               const string& arg) {      //!< argument to command   <-- THIS DOESN'T WORK
> >>     if ( arg == "" ) {
> >> [..]
> >> __________________________________________________________________ snip
> >>
> >>     It seems doxygen can't deal with this bracing style,
> >>     with the opening brace being on the same line as the argument:
> >>
> >> warning: The following parameters of AddLetterDialog::AskApp(..) are not documented: parameter 'arg'
> >> [..]
> >
> > My first guess is that the issue is the comment for the last argument is
> > no longer in the right context to refer to the argument, as it is no
> > long 'right after' the argument but is now inside the function.
> 
> 	Right, for sure it's the coding style, which indent(1)
> 	calls 'braces-on-func-def-line'.
> 
> 	I'd considered going with:
> 
> >> string AskApp(const char *cmd,          //!< command to send app
> >>               const string& arg         //!< argument to command
> >>              ) {
> >>     if ( arg == "" ) {
> 
> 	..which seems to work, but kinda defeats the purpose of the
> 	floating brace keeping the vertical size of the file small.
> 
> 	I decided to just stick with @param, and ensure the proper
> 	warning flags are enabled in Doxyfile.
> 
> > to place it in the right context. I personally use @param and look for
> > the warnings if things get out of sync.
> 
> 	Right, I'm of the same opinion.
> 
> 	It's too bad though; "//!<" is quite nice in that there's
> 	no way the names can get out of sync. It also removes the
> 	duplication of specifying the name twice; (once in docs,
> 	once in the code)
> 
> 	I'd log it as a bug, as I think doxygen should be able to
> 	cleverly handle different coding styles, but then there's this..
> 
> > As to the parameters coming after the returns, that is like because the
> > documentation is produced in the order it is in the file, (there is no
> > implicit sorting of these paragraphs) so since the parameters are
> > documented after the returns, that is how the documentation is produced.
> 
> 	Yes, it seems for instance even with '@param', if it appears after
> 	\returns, that changes the order. Huh.
> 
> 	And that pretty much puts to bed for me the idea of using '//!<'
> 	this way.. unless there's a way to force \returns to appear
> 	after params.
> 
> 	Thanks for the help -- wanted to make sure I wasn't missing something.

What does this produce:

/** This is my function
 *
 */
 
int myfunction (int universe, //!< This is the first argument
                int everything  //!< This is the second argument
                /**
                  * \returns An integer
                  */
                ) {
   return 42;
}

(Yes, this is probably really hokey...)



> 
> 
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
> 
>                                                                                                                             

-- 
Robert Heller             -- 978-544-6933
Deepwoods Software        -- Custom Software Services
http://www.deepsoft.com/  -- Linux Administration Services
he...@de...       -- Webhosting Services
                                                                                                         

Re: [Doxygen-users] doxygen commenting with //!< not working for last parameter of C++ methods

[Greg E. <er...@se...>]

On 05/12/18 08:47, Richard Damon wrote:
> On 5/11/18 2:44 PM, Greg Ercolano wrote:
>>
>>     I'd like to use //!< to comment the function/method parameters,
>>     but the coding style of the project seems to be causing trouble
>>     when it's used on the last argument:
>>
>> __________________________________________________________________ snip
>> [..]
>> string AskApp(const char *cmd,          //!< command to send app
>>               const string& arg) {      //!< argument to command   <-- THIS DOESN'T WORK
>>     if ( arg == "" ) {
>> [..]
>> __________________________________________________________________ snip
>>
>>     It seems doxygen can't deal with this bracing style,
>>     with the opening brace being on the same line as the argument:
>>
>> warning: The following parameters of AddLetterDialog::AskApp(..) are not documented: parameter 'arg'
>> [..]
>
> My first guess is that the issue is the comment for the last argument is
> no longer in the right context to refer to the argument, as it is no
> long 'right after' the argument but is now inside the function.

	Right, for sure it's the coding style, which indent(1)
	calls 'braces-on-func-def-line'.

	I'd considered going with:

>> string AskApp(const char *cmd,          //!< command to send app
>>               const string& arg         //!< argument to command
>>              ) {
>>     if ( arg == "" ) {

	..which seems to work, but kinda defeats the purpose of the
	floating brace keeping the vertical size of the file small.

	I decided to just stick with @param, and ensure the proper
	warning flags are enabled in Doxyfile.

> to place it in the right context. I personally use @param and look for
> the warnings if things get out of sync.

	Right, I'm of the same opinion.

	It's too bad though; "//!<" is quite nice in that there's
	no way the names can get out of sync. It also removes the
	duplication of specifying the name twice; (once in docs,
	once in the code)

	I'd log it as a bug, as I think doxygen should be able to
	cleverly handle different coding styles, but then there's this..

> As to the parameters coming after the returns, that is like because the
> documentation is produced in the order it is in the file, (there is no
> implicit sorting of these paragraphs) so since the parameters are
> documented after the returns, that is how the documentation is produced.

	Yes, it seems for instance even with '@param', if it appears after
	\returns, that changes the order. Huh.

	And that pretty much puts to bed for me the idea of using '//!<'
	this way.. unless there's a way to force \returns to appear
	after params.

	Thanks for the help -- wanted to make sure I wasn't missing something.

Re: [Doxygen-users] doxygen commenting with //!< not working for last parameter of C++ methods

[Richard D. <Ri...@Da...>]

On 5/11/18 2:44 PM, Greg Ercolano wrote:
>     I'm embarking on a C++ project, and want to get the doxygen comments
>     right before the project gets too far along.
>
>     I'd like to use //!< to comment the function/method parameters,
>     but the coding style of the project seems to be causing trouble
>     when it's used on the last argument:
>
> __________________________________________________________________ snip
>
> /// Send a message to main application asking for a result
> ///
> /// \returns a single string reply from the app.
> ///
> string AskApp(const char *cmd,          //!< command to send app
>               const string& arg) {      //!< argument to command
>     if ( arg == "" ) {
>         ..stuff..
>     }
>     ..stuff..
> }
> __________________________________________________________________ snip
>
>     It seems doxygen can't deal with this bracing style,
>     with the opening brace being on the same line as the argument:
>
> warning: The following parameters of AddLetterDialog::AskApp(..) are not documented: parameter 'arg'
>
>     I'll use @param if I have to, as I've used that on other projects
>     that use this same bracing style (FLTK), but it's too easy for the
>     @param comments to get out of sync with the code if the argument
>     name changes. So //!< seems preferable. It also makes for less lines
>     in the code.
>
>     Is there a Doxyfile flag I'm missing for bracing style, or is this a bug?
>
> PS. Also, with the //!< comment style, for some reason doxygen is
>     putting the parameters BELOW the return docs instead of above,
>     which seems counter to convention.
>
My first guess is that the issue is the comment for the last argument is
no longer in the right context to refer to the argument, as it is no
long 'right after' the argument but is now inside the function.

You could try documenting with something like

  const string& arg /**<   arguement to command */ ){

or

  const string& arg        //!< argument to command

){

to place it in the right context. I personally use @param and look for
the warnings if things get out of sync.

As to the parameters coming after the returns, that is like because the
documentation is produced in the order it is in the file, (there is no
implicit sorting of these paragraphs) so since the parameters are
documented after the returns, that is how the documentation is produced.

-- 
Richard Damon

[Doxygen-users] doxygen commenting with //!< not working for last parameter of C++ methods

[Greg E. <er...@se...>]

    I'm embarking on a C++ project, and want to get the doxygen comments
    right before the project gets too far along.

    I'd like to use //!< to comment the function/method parameters,
    but the coding style of the project seems to be causing trouble
    when it's used on the last argument:

__________________________________________________________________ snip

/// Send a message to main application asking for a result
///
/// \returns a single string reply from the app.
///
string AskApp(const char *cmd,          //!< command to send app
              const string& arg) {      //!< argument to command
    if ( arg == "" ) {
        ..stuff..
    }
    ..stuff..
}
__________________________________________________________________ snip

    It seems doxygen can't deal with this bracing style,
    with the opening brace being on the same line as the argument:

warning: The following parameters of AddLetterDialog::AskApp(..) are not documented: parameter 'arg'

    I'll use @param if I have to, as I've used that on other projects
    that use this same bracing style (FLTK), but it's too easy for the
    @param comments to get out of sync with the code if the argument
    name changes. So //!< seems preferable. It also makes for less lines
    in the code.

    Is there a Doxyfile flag I'm missing for bracing style, or is this a bug?

PS. Also, with the //!< comment style, for some reason doxygen is
    putting the parameters BELOW the return docs instead of above,
    which seems counter to convention.

Re: [Doxygen-users] Header file parsed without '\file' ('@file')

[Travis E. <tra...@gm...>]

I think Doxygen's still going to parse anything that matches your input
config; it just doesn't necessarily document it.

Regarding the warnings themselves, see WARN_IF_UNDOCUMENTED.

On Thu, May 10, 2018 at 4:02 AM Joe Bloggs <pub...@gm...>
wrote:

> Hi,
>
> My understanding is that each file to be parsed by Doxygen should have at
> minimum the '\file' or '@file' command.  I have a simple example where I
> get warnings from a file that shouldn't be parsed.  The steps to reproduce
> are (Doxygen v1.8.14)
>
> 1) create a new empty directory
> 2) in the directory create "example.h" with the following content:
>
> typedef struct
> {
> int i;
> } S;
>
> 3) auto-generate a Doxyfile with "doxygen -g"
> 4) run Doxygen
>
> I see two warnings:
>
> C:/temp/example.h:2: warning: Compound S is not documented.
> C:/temp/example.h:3: warning: Member i (variable) of class S is not
> documented.
>
> I can see in the auto-generated Doxyfile that EXTRACT_ALL = NO so why do I
> get these warnings when 'example.h' doesn't have '\file' or '@file'?
>
> Thanks.
>
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>

[Doxygen-users] Header file parsed without '\file' ('@file')

[Joe B. <pub...@gm...>]

Hi,

My understanding is that each file to be parsed by Doxygen should have at
minimum the '\file' or '@file' command.  I have a simple example where I
get warnings from a file that shouldn't be parsed.  The steps to reproduce
are (Doxygen v1.8.14)

1) create a new empty directory
2) in the directory create "example.h" with the following content:

typedef struct
{
int i;
} S;

3) auto-generate a Doxyfile with "doxygen -g"
4) run Doxygen

I see two warnings:

C:/temp/example.h:2: warning: Compound S is not documented.
C:/temp/example.h:3: warning: Member i (variable) of class S is not
documented.

I can see in the auto-generated Doxyfile that EXTRACT_ALL = NO so why do I
get these warnings when 'example.h' doesn't have '\file' or '@file'?

Thanks.

[Doxygen-users] Make server side search work

[Fabian C. <Cen...@in...>]

Hi

We put the doxygen generated documentation on a server and used
the client side search previously. However some words could not be
found as the client side search is not a full text search. That's why
we now wanted to switch to server side search to get better results.

The server is a linux with Apache with php, we also have e.g. MantisBT
(bugtracker) and DocuWiki running on the same server, so php (7) is
running fine. The documentation is generated on a different computer
and then the whole html directory (output from doxygen) is copied
to the live server.

But when I try to search for something no results are returned, just
like in this question:

https://stackoverflow.com/questions/48440476/doxygen-server-side-searching-does-not-work

These are the options from my Doxyfile:

SEARCHENGINE           = YES
SERVER_BASED_SEARCH    = YES
EXTERNAL_SEARCH        = NO
SEARCHENGINE_URL       =
SEARCHDATA_FILE        = searchdata.xml

In the html/search directory is a search.idx file with all the text strings.
I don't see errors in the logfiles in /var/log/.

Is something else needed? Is there some debugging I can enable?

Thanks

bye  Fabi

Re: [Doxygen-users] \todo inside C# XML comment

[Nelis O. <noo...@co...>]

Hallo

I can confirm we're seeing the same issue (1.18.14). Our workaround was to use the \todo outside of a tag, e.g.:
      /// <summary>
      /// The size of the font.
      /// </summary>
      /// \todo rename to MyFontSize
      Int MySize { get; set; }

I still think it is a bug, or if not the bug report should be closed and taken up in the known issues/clarified in the \todo or C# (XML) documentation.

-----Original Message-----
From: Clemens Feige [mailto:c....@os...] 
Sent: maandag 7 mei 2018 18:31
To: Doxygen-users <dox...@li...>
Subject: [Doxygen-users] \todo inside C# XML comment

Hello

I have an issue with the \todo command being used inside C# XML comments:

Warnings are generated inside the log-file:
   "warning:Unexpected tag dd found"

The HTML output of the TODO list (at "related pages") is damaged. Note that technically the TODO list is made from a HTML "description list" 
which may explain the mysterious warning about the <dd> tag.

I believe my issue is essentially the same as bug #746419

https://bugzilla.gnome.org/show_bug.cgi?id=746419#c0

I can confirm that entering a empty comment line after the \todo mysteriously improve the situation.

I have a minimal working example. Shall I append this to the ticket (which is from 2015) or create a new ticket?

Has anybody the same observation?

Thanks
Clemens

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot _______________________________________________
Doxygen-users mailing list
Dox...@li...
https://lists.sourceforge.net/lists/listinfo/doxygen-users

==============================================

"The information contained in this e-mail message may be confidential information, and may also be privileged. If you are not the intended recipient, any use, interference with, disclosure or copying of this material is unauthorised and prohibited. If you have received this message in error, please notify us by return email and delete the original message."

Re: [Doxygen-users] Unexpected warning after upgrading to Doxygen 1.8.14

[Geoff A. <geo...@gm...>]

@assertion_exception{e} is an alias I define in my Doxyfile:

	ALIASES   = "assertion_exception=@exception
assertion_exception\nalways" \
                         "assertion_exception{1}=@exception
assertion_exception\n<code>\1</code> is <code>false</code>" \
                         "assertion_exception{2}=\assertion_exception{\1}
(only when <code>#ECCL_DEBUG >= \2</code>)" \
                         "Cpp11=The <i>2011 C++ Standard</i> (INCITS/ISO/IEC
14882-2011[2012])" \
                         "Cpp11short=The <i>2011 C++ Standard</i>" \
                         "cpp11=the <i>2011 C++ Standard</i> (INCITS/ISO/IEC
14882-2011[2012])" \
                         "cpp11short=the <i>2011 C++ Standard</i>"

Geoff Alexander

-----Original Message-----
From: Richard Damon <Ri...@Da...> 
Sent: Saturday, May 05, 2018 9:50 AM
To: dox...@li...
Subject: Re: [Doxygen-users] Unexpected warning after upgrading to Doxygen
1.8.14

On 5/5/18 1:05 AM, Geoff Alexander wrote:
>
> I get an unexpected warning with Doxygen 1.8.14, which I don’t get 
> with Doxygen 1.8.13.
>
>  
>
>    gdlxn@linux-6edc:~/bugs/b159> /usr/local/doxygen-1.8.13/bin/doxygen
> Doxyfile.1.8.13
>
>    gdlxn@linux-6edc:~/bugs/b159> /usr/local/doxygen-1.8.14/bin/doxygen
> Doxyfile.1.8.14
>
>    /home/gdlxn/bugs/b159/test1.hpp:5: warning: unexpected token in 
> comment block while parsing the argument of command exception
>
>  
>
> Here's the contents of test1.hpp:
>
>  
>
> --- begin ---
>
> /**
>
> * ECCL_ASSERT(e) is a macro that throws an eccl::assertion_exception 
> if
>
> * @a e is <code>false</code>.
>
> *
>
> * @param e the expression tested
>
> *
>
> * @assertion_exception{e}
>
> */
>
> #define ECCL_ASSERT(e) \
>
>   if (!(e)) { \
>
>       std::string message = "\""; \
>
>       message += #e; \
>
>       message += "\" is false"; \
>
>       throw eccl::assertion_exception(message); \
>
>   }
>
> --- end ---
>
>  
>
> Is this a known bug in Doxygen 1.8.14?  If not, what's the best way to 
> report it?
>
>  
>
> Thanks,
>
> Geoff Alexander
>
What is @assertion_exception ?

--
Richard Damon


----------------------------------------------------------------------------
--
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Doxygen-users mailing list
Dox...@li...
https://lists.sourceforge.net/lists/listinfo/doxygen-users

[Doxygen-users] \todo inside C# XML comment

[Clemens F. <c....@os...>]

Hello

I have an issue with the \todo command being used inside C# XML comments:

Warnings are generated inside the log-file:
   "warning:Unexpected tag dd found"

The HTML output of the TODO list (at "related pages") is damaged. Note 
that technically the TODO list is made from a HTML "description list" 
which may explain the mysterious warning about the <dd> tag.

I believe my issue is essentially the same as bug #746419

https://bugzilla.gnome.org/show_bug.cgi?id=746419#c0

I can confirm that entering a empty comment line after the \todo 
mysteriously improve the situation.

I have a minimal working example. Shall I append this to the ticket 
(which is from 2015) or create a new ticket?

Has anybody the same observation?

Thanks
Clemens

Re: [Doxygen-users] External documentation links

[Mark <dox...@er...>]

> On May 7, 2018, at 18:49, Mark <dox...@er...> wrote:
> 
> So I ask again, is the a way to explicitly disambiguate my umbrella doc’s index from libktx’s?

Bonus question: is there someway to use a URL as the name for the reference “name” in \subpage command? Just putting a URL after it results in "unable to resolve reference to `a’

Trying a markdown style URL reference instead of an <a href=“…"> results in a similar message.

Regards

    -Mark

Re: [Doxygen-users] External documentation links

[Mark <dox...@er...>]

I am still seeking help with the following questions.

> On Apr 22, 2018, at 22:26, Mark <dox...@er...> wrote:
> 
> I’m experimenting with TAG files and external links and have a couple of questions.
> 
> 1. Is it possible to disambiguate links in refs? I want to link to the index page of an external doc set for an API. I have
> 
> @subpage index
> 
> in the document doing the referencing. It is linking back to itself ‘cos it is also named index.

I have found that if I hand edit the tag file changing

  <compound kind="page">
    <name>index</name>
    <title>Introduction</title>
    <filename>index</filename>
    ...
 </compound>

to

  <compound kind="page">
    <name>libktx_index</name>
    <title>Introduction</title>
    <filename>libktx_index</filename>
    ...
 </compound>

then the link from the external document works. However I need to change both <name> and <filename> otherwise doxygen reports that it is unable to resolve the reference to “libktx_index” when it is processing the doc that reads the tag file. This is unfortunate as I want the filename to remain index.html for ease of web use. Also I haven’t found any setting that would let me change this name. index corresponds to the page called “mainpage” in the source doc.

So I ask again, is the a way to explicitly disambiguate my umbrella doc’s index from libktx's?

> 
> 1a. If not, how can I tell Doxygen to use something other than “index” for the starting page when generating the external API doc?
> 
> 2. Is there some way to reference an external page at the page level rather than subpage? If I try
> 
> @page externalref
> 
> Nothing appears. Only if I use
> 
> @subpage externalref
> 
> do I get a usable link.

I have not made any progress with this one.

Regards

    -Mark

Re: [Doxygen-users] Unexpected warning after upgrading to Doxygen 1.8.14

[Richard D. <Ri...@Da...>]

On 5/5/18 1:05 AM, Geoff Alexander wrote:
>
> I get an unexpected warning with Doxygen 1.8.14, which I don’t get
> with Doxygen 1.8.13.
>
>  
>
>    gdlxn@linux-6edc:~/bugs/b159> /usr/local/doxygen-1.8.13/bin/doxygen
> Doxyfile.1.8.13
>
>    gdlxn@linux-6edc:~/bugs/b159> /usr/local/doxygen-1.8.14/bin/doxygen
> Doxyfile.1.8.14
>
>    /home/gdlxn/bugs/b159/test1.hpp:5: warning: unexpected token in
> comment block while parsing the argument of command exception
>
>  
>
> Here's the contents of test1.hpp:
>
>  
>
> --- begin ---
>
> /**
>
> * ECCL_ASSERT(e) is a macro that throws an eccl::assertion_exception if
>
> * @a e is <code>false</code>.
>
> *
>
> * @param e the expression tested
>
> *
>
> * @assertion_exception{e}
>
> */
>
> #define ECCL_ASSERT(e) \
>
>   if (!(e)) { \
>
>       std::string message = "\""; \
>
>       message += #e; \
>
>       message += "\" is false"; \
>
>       throw eccl::assertion_exception(message); \
>
>   }
>
> --- end ---
>
>  
>
> Is this a known bug in Doxygen 1.8.14?  If not, what's the best way to
> report it?
>
>  
>
> Thanks,
>
> Geoff Alexander
>
What is @assertion_exception ?

-- 
Richard Damon

[Doxygen-users] Unexpected warning after upgrading to Doxygen 1.8.14

[Geoff A. <geo...@gm...>]

I get an unexpected warning with Doxygen 1.8.14, which I don't get with
Doxygen 1.8.13.

 

   gdlxn@linux-6edc:~/bugs/b159> /usr/local/doxygen-1.8.13/bin/doxygen
Doxyfile.1.8.13

   gdlxn@linux-6edc:~/bugs/b159> /usr/local/doxygen-1.8.14/bin/doxygen
Doxyfile.1.8.14

   /home/gdlxn/bugs/b159/test1.hpp:5: warning: unexpected token in comment
block while parsing the argument of command exception

 

Here's the contents of test1.hpp:

 

--- begin ---

/**

* ECCL_ASSERT(e) is a macro that throws an eccl::assertion_exception if

* @a e is <code>false</code>.

*

* @param e the expression tested

*

* @assertion_exception{e}

*/

#define ECCL_ASSERT(e) \

  if (!(e)) { \

      std::string message = "\""; \

      message += #e; \

      message += "\" is false"; \

      throw eccl::assertion_exception(message); \

  }

--- end ---

 

Is this a known bug in Doxygen 1.8.14?  If not, what's the best way to
report it?

 

Thanks,

Geoff Alexander

[Doxygen-users] External function documentation in markdown files

[Joe B. <pub...@gm...>]

Hi,

Is it possible to use the 'fn' command in markdown files?

'example.c':

    /*!
    * \file
    */
    void example(int i)
    {
        /* do something */
    }

'doc.md':

    Title
    =====
    \fn void example(int i)
    \brief An example
    \param i A parameter

When I run 'example.c' and 'doc.md' through Doxygen I get two warnings:

    doc.md:3: warning: member with no name found.
    example.c:4: warning: Member example(int i) (function) of file
example.c is not documented.

Thanks.

[Doxygen-users] snippet woes

[Mark <dox...@er...>]

I am having problems with the snippet command.

In one of my source files, glloader.c I have

/**
 * @example glloader.c
 * This is an example of using the low-level ktxTexture API to create and load
 * an OpenGL texture. It is a fragment of the code used by
 * @ref ktxTexture_GLUpload which underpins the @c ktxLoadTexture* functions.
 *
 * @code
 * #include <ktx.h>
 * @endcode
 *
 * This structure is used to pass to a callback function data that is uniform
 * across all images.
 * @snippet this cbdata
 *
 * One of these callbacks, selected by @ref ktxTexture_GLUpload based on the
 * dimensionality and arrayness of the texture, is called from
 * @ref ktxTexture_IterateLevelFaces to upload the texture data to OpenGL.
 * @snippet this imageCallbacks
 *
 * This function creates the GL texture object and sets up the callbacks to
 * load the image data into it.
 * @snippet this loadGLTexture
 */

When my block ids are marked as special comments (e.g. /**, /*!) Doxygen inserts the block ids into the documentation for the function immediately following the block id as well as using them as block ids. I solved this by changing the block id comments into regular comments. I don’t know if this a doxygen bug or a documentation problem. The doc gives only 1 example of a block id and it uses a special comment “//!”.

Another issue is that following the last snippet, Doxygen is including the entire glloader.c file in the “glloader.c” example that it generates. If I wanted to included the whole file I wouldn’t be using snippets. How can I stop Doxygen doing this?

Regards

    -Mark

[Doxygen-users] Found some issues generating Latex from C#

[Nelis O. <noo...@co...>]

Hallo

We switched to doxygen (1.8.14) for generating our documentation (C# -> Latex). We found some issues, i'm not sure whether or not these are bugs or expected behavior (or misconfiguration on our end). I know it is quite a list, feel free to answer in parts.

I have attached example code. More detailed information is provided with the examples, a high level overview:


1)      The detailed description (subsubsection) is always shown, even though no <remarks /> tag is provided and ALWAYS_DETAILED_SEC = NO.

2)      (latex source code) properties under Property Documentation do not always start their \hbox{...} on a new line -> causes formatting issues.

3)      Abstract classes are nor marked as abstract.

4)      Constructors are marked as inline.

5)      Namespace in <see cref=""> are not shortened even though HIDE_SCOPE_NAMES = YES, i guess this is expected behavior?

6)      The Additional Inherited Members is always shown even though it is empty

7)      Internal classes are still present in the Classes list (under Namespace references), even though doxygen is configured to ignore internals.

8)      <inheritdoc/> does not work for properties and gives warnings for functions (params and return type missing) (looks like this was reported before: https://sourceforge.net/p/doxygen/discussion/130994/thread/0af65154/)

9)      Namespaces are automatically made a hyperlink in the documentation, for example: namespace Test.Exceptions -> will cause every occurrence of the word "Exceptions", in the documentation, to be a hyperlink.

Some issues i could not reproduce/provide a minimal example for:

10)   The parsing sometimes goes wrong when using \todo{}, i have had:

o   Warning: error : return type of member XXX is not documented (warning treated as error, aborting now) when using \todo{} in the remarks above the returns tag.

o   HTML generation: infinite loop/assert failure; same one as reported here: http://doxygen.10944.n7.nabble.com/ASSERT-quot-0-quot-in-docparser-cpp-5747-td7738.html. (removing \todo out of the documentation resolves this issue). This is on Windows 7 (64bit).

11)   I got Latex warnings about multiple defined labels.

Some additional findings/remarks:

12)   Why is \newcommand{\+}{\discretionary{\mbox{\scriptsize$\hookleftarrow$}}{}{}} defined in the header.tex instead of the syl? (it won't work without defining the command)

13)   Why hijack \paragraph for Property Documentation entries? This may be annoying if one wants to include a custom section (text) before the documentation (if that uses \paragraph; or \subparagraph for that matter). You can use the \usepackage{titlesec} package to define custom titles if so desired.

14)   \usepackage{fixltx2e} in header.tex is no longer required or do you want it to be compatible with older tex installations? (generates: fixltx2e Warning: fixltx2e is not required with releases after 2015)

15)   If one provides a custom header.tex and it ends with a comment (e.g. %--- Begin generated content ---) the first title will be missing. The first line of the generated content will be appended, instead of starting on a new line, (and thus be commented). Therefor the header.tex may not end on a comment.

I tried to filter out all already known issues. We also encountered these (already reported) bugs:

16)   https://bugzilla.gnome.org/show_bug.cgi?id=780439 -> i would expect both classes to be in the list + in the documentation

17)   https://bugzilla.gnome.org/show_bug.cgi?id=638606 (fixed)

18)   https://bugzilla.gnome.org/show_bug.cgi?id=794509 (fixed)

19)   https://bugzilla.gnome.org/show_bug.cgi?id=777746 (fixed)

Thanks in advance.



==============================================

"The information contained in this e-mail message may be confidential information, and may also be privileged. If you are not the intended recipient, any use, interference with, disclosure or copying of this material is unauthorised and prohibited. If you have received this message in error, please notify us by return email and delete the original message."

[Doxygen-users] License for images in generated output

[Sommefeldt, R. <Rys...@am...>]

Hi there,

Is there any applied license for the images included in generated doxygen output? The documentation states that “Documents produced by doxygen are derivative works derived from the input used in their production; they are not affected by this license". Does that also apply to the included images?

Best regards,

Rys Sommefeldt

[Doxygen-users] Found some issues generating Latex from C#

[Nelis O. <noo...@co...>]

Hallo

We switched to doxygen (1.8.14) for generating our documentation (C# -> Latex). We found some issues, i'm not sure whether or not these are bugs or expected behavior (or misconfiguration on our end). I know it is quite a list, feel free to answer in parts.

I have attached example code. More detailed information is provided with the examples, a high level overview:


1)      The detailed description (subsubsection) is always shown, even though no <remarks /> tag is provided and ALWAYS_DETAILED_SEC = NO.

2)      (latex source code) properties under Property Documentation do not always start their \hbox{...} on a new line -> causes formatting issues.

3)      Abstract classes are nor marked as abstract.

4)      Constructors are marked as inline.

5)      Namespace in <see cref=""> are not shortened even though HIDE_SCOPE_NAMES = YES, i guess this is expected behavior?

6)      The Additional Inherited Members is always shown even though it is empty

7)      Internal classes are still present in the Classes list (under Namespace references), even though doxygen is configured to ignore internals.

8)      <inheritdoc/> does not work for properties and gives warnings for functions (params and return type missing) (looks like this was reported before: https://sourceforge.net/p/doxygen/discussion/130994/thread/0af65154/)

9)      Namespaces are automatically made a hyperlink in the documentation, for example: namespace Test.Exceptions -> will cause every occurrence of the word "Exceptions", in the documentation, to be a hyperlink.

Some issues i could not reproduce/provide a minimal example for:

10)   The parsing sometimes goes wrong when using \todo{}, i have had:

o   Warning: error : return type of member XXX is not documented (warning treated as error, aborting now) when using \todo{} in the remarks above the returns tag.

o   HTML generation: infinite loop/assert failure; same one as reported here: http://doxygen.10944.n7.nabble.com/ASSERT-quot-0-quot-in-docparser-cpp-5747-td7738.html. (removing \todo out of the documentation resolves this issue)

11)   I got Latex warnings about multiple defined labels.

Some additional findings/remarks:

12)   Why is \newcommand{\+}{\discretionary{\mbox{\scriptsize$\hookleftarrow$}}{}{}} defined in the header.tex instead of the syl? (it won't work without defining the command)

13)   Why hijack \paragraph for Property Documentation entries? This may be annoying if one wants to include a custom section (text) before the documentation (if that uses \paragraph; or \subparagraph for that matter). You can use the \usepackage{titlesec} package to define custom titles if so desired.

14)   \usepackage{fixltx2e} in header.tex is no longer required or do you want it to be compatible with older tex installations? (generates: fixltx2e Warning: fixltx2e is not required with releases after 2015)

15)   If one provides a custom header.tex and it ends with a comment (e.g. %--- Begin generated content ---) the first title will be missing. The first line of the generated content will be appended, instead of starting on a new line, (and thus be commented). Therefor the header.tex may not end on a comment.

I tried to filter out all already known issues. We also encountered these (already reported) bugs:

16)   https://bugzilla.gnome.org/show_bug.cgi?id=780439 -> i would expect both classes to be in the list

17)   https://bugzilla.gnome.org/show_bug.cgi?id=638606 (fixed)

18)   https://bugzilla.gnome.org/show_bug.cgi?id=794509 (fixed)

19)   https://bugzilla.gnome.org/show_bug.cgi?id=777746 (fixed)

Thanks in advance.



==============================================

"The information contained in this e-mail message may be confidential information, and may also be privileged. If you are not the intended recipient, any use, interference with, disclosure or copying of this material is unauthorised and prohibited. If you have received this message in error, please notify us by return email and delete the original message."

Re: [Doxygen-users] doxygen message I don't understand

[D. R. E. <doc...@gm...>]

Jakob van Bethlehem wrote on 04/19/2018 11:48 AM:
> Hej,
> 
> AFAIU Doxygen uses its entirely own parser - my guess is that this parser simply doesn’t support decltype() yet 

You're probably right; decltype was officially introduced in C++11 (although I
think it was available in g++ for a while before that, IIRC) so it hadn't
really occurred to me as a serious proposition that it simply wasn't
understood by the doxygen parser. I thought it considerably more likely that I
was doing something stupid.

> - the way to fix this, is to create a patch for Doxygen, and send it, so it finds its way to the next official release. 

True. I have my hands full with other projects, both proprietary and
open-source, though.

> For the time being though, ...

Good suggestion; thank you.

I've been pondering whether to use the trick you mention, but on balance I
think I'll just leave the code so that it emits the error message, and put a
comment in the code. There are already more unnatural comment structures than
I like, merely for the purpose of appeasing the doxygen parser, so I'm
disinclined to add further pinchbeck commentary.

  Doc

-- 
Web:  http://enginehousebooks.com/drevans

[Doxygen-users] explicit link request to 'notice' could not be resolved

[Mark <dox...@er...>]

I have a markdown file, notice.md, whose 1st 2 lines are

Notice     {#notice}
=====

When I run doxygen with this, it reports for this line

"explicit link request to 'notice' could not be resolved”.

I can’t figure out why. The doc includes 2 other markdown documents with similarly structured titles that are working fine. I even copied the 1st 2 lines from one of those into notice.md but get the same message, modulo the link name. The file modes are identical. The files are all included in the doxyfile’s INPUT.

Can someone give me a clue as to what is going wrong?

Regards

    -Mark

[Doxygen-users] \includedoc and Markdown

[Mark <dox...@er...>]

I have a markdown doc that has, among many others, the following lines

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

@includedoc NOTICE.md

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

NOTICE.md is being included but is being formatted as a single paragraph instead of the multiple paragraphs it actually contains and are seen when the file is viewed as a page in the documentation.

Is this a bug or am I doing something wrong?

Regards

    -Mark