doxygen-users — List for users of doxygen

[Doxygen-users] \copydoc warning - target of \copydoc command not found

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

I have hundreds (almost one thousand!) of \copydoc statements which are
producing the following warning message.
Warning: target testClassX::innerClassX::getYes() of \copydoc command not
found

Here is the situation.
There is a C++ class, called testClassX.cpp
Here are its contents:

// Start testClassX.cpp

namespace abc {

namespace def {
class testClassX::InnerClassX {
  /*! \brief blah blah
   * \details prints stuff out
   */
  void printIt() {
	printStuff();
    }
  
  bool getYes() {
	return true;
   }
}

    testClassX::testClassX() {
        innerClassX_ = new InnerClassX;
    }

    /*! \copydoc testClassX::InnerClassX::printIt() */
    void testClassX::printIt() {
        innerClassX_->printIt();
    }

    /*! \copydoc Catalog::Impl::load() */
    bool testClassX::getYes() {
        return InnerClassX_->getYes();
    }

}
}

// End testClassX.cpp


The above example, when run through doxygen, yields:

Warning: target testClassX::innerClassX::getYes() of \copydoc command not
found
(However, there is no warning message for printIt(). Is this because it does
not return any parameters?)

Note that the class testClassX is declared in the .h file. 

What is wrong in the above example? How can I get rid of those \copydoc
related warnings?



--
View this message in context: http://doxygen.10944.n7.nabble.com/copydoc-warning-target-of-copydoc-command-not-found-tp6345.html
Sent from the Doxygen - Users mailing list archive at Nabble.com.

[Doxygen-users] \copydoc warning message for inner class: target of \copydoc not found

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

I have hundreds (almost one thousand!) of \copydoc statements which are
producing the following warning message.
Warning: target testClassX::innerClassX::getYes() of \copydoc command not
found

Here is the situation.
There is a C++ class, called testClassX.cpp
Here are its contents:

// Start testClassX.cpp

namespace abc {

namespace def {
class testClassX::innerClassX {
  /*! \brief blah blah
   * \details prints stuff out
   */
  void printIt() {
	printStuff();
    }
  
  bool getYes() {
	return true;
   }
}

    testClassX::testClassX() {
        testClassX_ = new testClassX;
    }

    /*! \copydoc testClassX::InnerClassX::printIt() */
    void testClassX::printIt() {
        testClassX_->printIt();
    }

    /*! \copydoc Catalog::Impl::load() */
    bool testClassX::getYes() {
        return testClassX_->getYes();
    }

}
}

// End testClassX.cpp


The above example, when run through doxygen, yields:

Warning: target testClassX::innerClassX::getYes() of \copydoc command not
found
(However, there is no warning message for printIt(). Is this because it does
not return any parameters?)

Note that the class testClassX is declared in the .h file. 

What is wrong in the above example? How can I get rid of those \copydoc
related warnings?



--
View this message in context: http://doxygen.10944.n7.nabble.com/copydoc-warning-message-for-inner-class-target-of-copydoc-not-found-tp6344.html
Sent from the Doxygen - Users mailing list archive at Nabble.com.

[Doxygen-users] Need developer for implementing external search

[Wilfred N. <wil...@ho...>]

We need someone to help with the implementation of server side search 
functionality for Doxygen. We use an application server that includes 
SQLite and where server side applications are designed in the Lua 
scripting language.

Thanks,
Wilfred

[Doxygen-users] Meaning of "Read" label on function description

[pdbarnes <pdb...@ll...>]

The generated html labels functions by access specifier, as in:
static struct Resolution* ns3::Time::PeekResolution	(	void 		)	inline static
read private 
(C++ example taken from  ns-3
<https://www.nsnam.org/docs/doxygen/classns3_1_1_time.html#a0b023c55c20582aa7c1781aacf128034> 
)
inline, static and private are obvious.
What does "read" mean?
Thanks,
Peter




--
View this message in context: http://doxygen.10944.n7.nabble.com/Meaning-of-Read-label-on-function-description-tp6340.html
Sent from the Doxygen - Users mailing list archive at Nabble.com.

[Doxygen-users] Meaning of function label "read"

[Barnes, P. D. <bar...@ll...>]

Hello Folks,

The generated html labels functions by access specifier, as in:

static struct Resolution* ns3::Time::PeekResolution (void) inline static read private

(C++ example taken from ns-3:
https://www.nsnam.org/docs/doxygen/classns3_1_1_time.html#a0b023c55c20582aa7c1781aacf128034 
)

"inline", "static" and "private" are obvious.

What does "read" mean?

Thanks,
Peter

[Doxygen-users] Specify language in doxy comments

[Barnes, P. D. <bar...@ll...>]

Hello Folks,

Is it possible to specify the source language in a Doxygen comment itself?  

Use case:  we have several files *without* standard extensions, and differing languages.  The file names can't be changed.  While 

	EXTENSION_MAPPING = no_extension=x

can be used to fix one of the languages, that leaves the others interpreted as the wrong language.

Something like this:

<File: example>
	/**
	 *  \file example
	 *  \lang .py
	 */
	...

would solve this case.

Any help would be appreciated.
Peter

Re: [Doxygen-users] Unable to include bullet list in brief paragraph

[John K. <jko...@ex...>]

Thanks to all for their suggestions. I finally got the results I wanted by
using the following:

/**
 *   <summary>
 *      <em>Purpose:</em>
 *      <list type="bullet">
 *          <item>Item 1.</item>
 *          <item>Item 2.</item>
 *          <item>Item 3.</item>
 *      </list>
 *   </summary>
 *
 *    Lots of detailed description goes here . . .
*/

-- john

From: Ron Wilson [mailto:ron...@gm...] 
Sent: Wednesday, October 23, 2013 07:10
To: doxygen-users
Subject: Re: [Doxygen-users] Unable to include bullet list in brief
paragraph

> From: John Koehring <jkoehring@ex...> - 2013-10-22 01:25
> I am using Doxygen 1.8.5 on Windows 7 and am trying to include
> a bullet list in a brief paragraph for a C++ class. I want the brief
> paragraph, including the list, to be displayed in the Class List and
> at the top of the Class Reference page.
Have you tried setting the MULTILINE_CPP_IS_BRIEF option
in your doxygen configuration?
But that might not work. List mark-up is likely considered paragraph
mark-up, so might end the @brief section.

Re: [Doxygen-users] Unable to include bullet list in brief paragraph

[Ron W. <ron...@gm...>]

> From: John Koehring <jkoehring@ex...> - 2013-10-22 01:25
> I am using Doxygen 1.8.5 on Windows 7 and am trying to include
> a bullet list in a brief paragraph for a C++ class. I want the brief
> paragraph, including the list, to be displayed in the Class List and
> at the top of the Class Reference page.

Have you tried setting the MULTILINE_CPP_IS_BRIEF option
in your doxygen configuration?

But that might not work. List mark-up is likely considered paragraph
mark-up, so might end the @brief section.

[Doxygen-users] Unable to include bullet list in brief paragraph

[John K. <jko...@ex...>]

Hello,

 

I am using Doxygen 1.8.5 on Windows 7 and am trying to include a bullet list
in a brief paragraph for a C++ class. I want the brief paragraph, including
the list, to be displayed in the Class List and at the top of the Class
Reference page.

 

I have tried:

 

/// \a Purpose:

/// - Item 1.

/// - Item 2.

/// - Item 3.

/// .

 

/** 

 * Lots of detailed description goes here . . .

*/

class Foo

{

    // Class definition goes here . . .

}

 

And:

 

/**

* \brief \a Purpose:

*  - Item 1.

*  - Item 2.

*  - Item 3.

*  .

* 

 * Lots of detailed description goes here . . .

*/

class Foo

{

    // Class definition goes here . . .

}

 

And:

 

/**

* <summary>

* \a Purpose:

* - Item 1.

* - Item 2.

* - Item 3.

* .

* </summary>

* 

* Lots of detailed description goes here . . .

*/

class Foo

{

    // Class definition goes here . . .

}

 

And:

 

/**

* <summary>

*   <em>Purpose:</em>

*   <ul>

*      <li>Item 1.

*      <li>Item 2.

*      <li>Item 3.

*   </ul>

* </summary>

*

* Lots of detailed description goes here . . .

*/

class Foo

{

    // Class definition goes here . . .

}

 

And many other permutations. In all cases I have the following set in my
Doxyfile configuration file:

 

BRIEF_MEMBER_DESC      = YES

REPEAT_BRIEF           = YES

MULTILINE_CPP_IS_BRIEF = YES

MARKDOWN_SUPPORT       = NO

 

The results in all cases are the same. The only text displayed in the Class
List and at the top of the Foo Class Reference page is:

 

Purpose:

 

However, the Detailed Description section of the Foo Class Reference page
always displays Purpose:  followed by the properly formatted bullet list
followed by all the detailed description text. So it seems that Doxygen is
always treating my bullet list as part of the detailed description. Can
anyone tell me how to get my bullet list included as part of the brief
paragraph?

 

Thank you.

 

-- John Koehring

[Doxygen-users] Is IN_BODY_DOCS available for "Perl Module Output"?

[eignil <ei...@gm...>]

I put some comments in the function body of c program. They can be produced normally in HTML format, but nothing for the perl module. (HIDE_IN_BODY_DOCS was set to ’NO’ )

Is this a bug or a new feature that hasn’t implemented for perl module as it is still experimental ?

BTW, I used an modified version that can produce perl module with in body documents, but there are some bugs. 
So what is the condition of the official version to handle the perl module?

Thanks very much.

My test code is very simple:
source code: 

/**
 *@file
 */

/**
*@brif Inbody document test
*
*
*
*@remark end before function.
*/
int main(void){
    /**
     *Comment in function body
     */
    return 0;
}

Document as html:
Function Documentation

int main	(	void 		)	
Inbody document test

Remarks
end before function.
Comment in function body


content in  DoxDocs.pm: (“Comment in function body" disapear)

$doxydocs=
{
  classes => [
  ],
  namespaces => [
  ],
  files => [
    {
      name => 'test_main.c',
      includes => [
      ],
      included_by => [
      ],
      functions => {
        members => [
          {
            kind => 'function',
            name => 'main',
            virtualness => 'non_virtual',
            protection => 'public',
            static => 'no',
            brief => {},
            detailed => {
              doc => [
                {
                  type => 'text',
                  content => 'Inbody document test'
                },
                {
                  type => 'parbreak'
                },
                {
                  remark => [
                    {
                      type => 'text',
                      content => 'end before function. '
                    }
                  ]
                }
              ]
            },
            type => 'int',
            const => 'no',
            volatile => 'no',
            parameters => [
              {
                type => 'void'
              }
            ]
          }
        ]
      },
      brief => {},
      detailed => {}
    }
  ],
  groups => [
  ],
  pages => [
  ]
};
1;

PS: 
The document  of oxygen says "Doxygen allows you to put your documentation blocks practically anywhere (the exception is inside the body of a function or inside a normal C style comment block).”  
But in the same page before this they says “For methods and functions there is also a third type of description, the so called in bodydescription, which consists of the concatenation of all comment blocks found within the body of the method or function.” 
I was totally confused….

Re: [Doxygen-users] Call graph generation in Python seems to not work

[leeping <lpw...@gm...>]

Hi Dimitri,

Thank you.  The bug report has been submitted along with a smaller example
attached (i.e. the same call graphs are generated even if I generate docs
for nifty.py only.)

- Lee-Ping




--
View this message in context: http://doxygen.10944.n7.nabble.com/Call-graph-generation-in-Python-seems-to-not-work-tp6332p6334.html
Sent from the Doxygen - Users mailing list archive at Nabble.com.

Re: [Doxygen-users] Call graph generation in Python seems to not work

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

On Oct 18, 2013, at 12:07 , leeping <lpw...@gm...> wrote:

> Hi there,
> 
> I have a Doxygen documentation page located at
> http://leeping.github.io/forcebalance/doc/html/ .  The documentation
> generator works amazingly well, but the call graph generation seems to be
> broken for some functions defined in the Python module.
> 
> For instance, in this call graph, "uncommadash" appears to have a complex
> network of calls, but in reality it doesn't call any of these functions:
> http://leeping.github.io/forcebalance/doc/html/api/namespaceforcebalance_1_1nifty.html#afa670d68f01813ac8d429bc5cbdb4f9f
> 
> I also have an example on my GitHub issue list for this code base:
> https://github.com/leeping/forcebalance/issues/4
> 
> My doxygen configuration is here:
> https://github.com/leeping/forcebalance/blob/master/doc/.api.cfg
> 
> If someone could take a look at this issue, I would greatly appreciate it!

Looks like the parser lost track and included the next couple of functions as part of the uncommadash function.
Can you please file a bug report in the bug tracker for it with the above data? (attaching a small example capturing the problem would even be better)
Here is the link: https://bugzilla.gnome.org/enter_bug.cgi?product=doxygen

Regards,
  Dimitri

[Doxygen-users] Call graph generation in Python seems to not work

[leeping <lpw...@gm...>]

Hi there,

I have a Doxygen documentation page located at
http://leeping.github.io/forcebalance/doc/html/ .  The documentation
generator works amazingly well, but the call graph generation seems to be
broken for some functions defined in the Python module.

For instance, in this call graph, "uncommadash" appears to have a complex
network of calls, but in reality it doesn't call any of these functions:
http://leeping.github.io/forcebalance/doc/html/api/namespaceforcebalance_1_1nifty.html#afa670d68f01813ac8d429bc5cbdb4f9f

I also have an example on my GitHub issue list for this code base:
https://github.com/leeping/forcebalance/issues/4

My doxygen configuration is here:
https://github.com/leeping/forcebalance/blob/master/doc/.api.cfg

If someone could take a look at this issue, I would greatly appreciate it!

Thanks,

- Lee-Ping




--
View this message in context: http://doxygen.10944.n7.nabble.com/Call-graph-generation-in-Python-seems-to-not-work-tp6332.html
Sent from the Doxygen - Users mailing list archive at Nabble.com.

[Doxygen-users] More... links

[John Y. <jo...@ya...>]

Why are the generated "More..." links so often useless / vacuous?  I am
working with the a recent git snapshot but I have confirmed this behavior
back to 1.8.3.1.

As best I can tell if a symbol represents an object with additional internal
definitions then both that symbol's auto link and its More... link point to
its associated detail page.  By contrast, if a symbol is a leaf (e.g. class
method or data member) then the auto link points to that symbol's detail
page but the More... link simply points back to itself.  Is this not a bug?

/john



--
View this message in context: http://doxygen.10944.n7.nabble.com/More-links-tp6330.html
Sent from the Doxygen - Users mailing list archive at Nabble.com.

Re: [Doxygen-users] Problem documenting Fortran include file

[Jörg S. <Joe...@fg...>]

Dear Albert,

I understand your idea and your script. Good idea! But I do not know how I have to use the script in Doxygen. I will browse through the documentation on the weekend. Do you think there are no problems with modules? If the module name appear in the documentation, that would be a mistake.

Joerg

Re: [Doxygen-users] Problem documenting Fortran include file

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

Dear Joerg,

Biking home I got an idea: why not use doxygen filter pattern capabilities?
Did a small test with a python script:

import sys
import os

f = open(sys.argv[1],'r')
sys.stdout.write("      module
__anonymous_%s__\n"%os.path.splitext(os.path.basename(sys.argv[1].replace("\\","/")))[0])
sys.stdout.write(f.read())
sys.stdout.write("      end module\n")

wrapped it in a batch file and ran it. In my opinion good results.

Albert



On Thu, Oct 10, 2013 at 3:07 PM, Jörg Sichermann <Joe...@fg...
> wrote:

>  Dear Albert,****
>
> ** **
>
> thank you very much for your answer. I suppsed something like that, but I
> was unsure. At the moment I am documenting very old (form 1980 and older)
> Fortran code using Doxygen an because of this the issue is still relevant
> for me, too.****
>
> ** **
>
> Have a nice day,****
>
> Joerg****
>
> ___________________________________****
>
> ** **
>
> This e-mail and any attachments may contain confidential and/or privileged
> material; it is for the intended addressee(s) only. If you are not a named
> addressee, you must not use, retain or disclose such information.****
>
> ** **
>
> *Von:* Albert [mailto:alb...@gm...]
> *Gesendet:* Donnerstag, 10. Oktober 2013 14:57
> *An:* Jörg Sichermann
> *Cc:* dox...@li...
> *Betreff:* Re: [Doxygen-users] Problem documenting Fortran include file***
> *
>
> ** **
>
> Dear Joerg,****
>
> A bit of an old message , had to dig for the original mail, but it is
> still relevant.****
>
> The problem here is that there is no begin (SUBROUTINE, FUNCTION, MODULE,
> PROGRAM) and end statement it is, mot of the times, just a bunch of
> declarations. The inc files are coming from the older Fortran versions
> where there were no modules  available. ****
>
> By chance I had a small thought about it. For Programs (the main program
> is possible without program statement, the end statement though is
> mandatory) I implemented a while ago that in case the program statement is
> missing I create a dummy program statement with a name like (by
> head)__<file_name>__****
>
> For include files, well actually for files without begin and end statement
> I was thinking about something similar, defining a module with name
> __anonymous_<file_name>__****
>
> problem is that one only knows if it was an include file when the entire
> file has been read.****
>
> This problem is on my list, with a lot of other Fortran / doxygen problems.
> ****
>
> Albert****
>
> ** **
>
> On Thu, Oct 10, 2013 at 12:13 PM, Jörg Sichermann <
> joe...@fg...> wrote:****
>
> Dear Albert,
>
> I see the same error running Doxygen 1.8.5
> I saw the date of our message ( year 2010 ) - Does exist a solution now?
>
> Best Regards,
> Joerg
>
>
>
> --
> View this message in context:
> http://doxygen.10944.n7.nabble.com/Problem-documenting-Fortran-include-file-tp3694p6325.html
> Sent from the Doxygen - Users mailing list archive at Nabble.com.
>
>
> ------------------------------------------------------------------------------
> October Webinars: Code for Performance
> Free Intel webinars can help you accelerate application performance.
> Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most
> from
> the latest Intel processors and coprocessors. See abstracts and register >
> http://pubads.g.doubleclick.net/gampad/clk?id=60134071&iu=/4140/ostg.clktrk
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users****
>
> ** **
>

Re: [Doxygen-users] PATCH: New option PROJECT_LOGO_ANCHOR

[jpnurmi <jp...@gm...>]

Hi Jake,

I like the idea very much! Perhaps you could try submitting a pull request?

https://github.com/doxygen/doxygen/pulls

--
J-P Nurmi



--
View this message in context: http://doxygen.10944.n7.nabble.com/PATCH-New-option-PROJECT-LOGO-ANCHOR-tp2417p6327.html
Sent from the Doxygen - Users mailing list archive at Nabble.com.

Re: [Doxygen-users] Problem documenting Fortran include file

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

Dear Joerg,

A bit of an old message , had to dig for the original mail, but it is still
relevant.
The problem here is that there is no begin (SUBROUTINE, FUNCTION, MODULE,
PROGRAM) and end statement it is, mot of the times, just a bunch of
declarations. The inc files are coming from the older Fortran versions
where there were no modules  available.
By chance I had a small thought about it. For Programs (the main program is
possible without program statement, the end statement though is mandatory)
I implemented a while ago that in case the program statement is missing I
create a dummy program statement with a name like (by head)__<file_name>__
For include files, well actually for files without begin and end statement
I was thinking about something similar, defining a module with name
__anonymous_<file_name>__
problem is that one only knows if it was an include file when the entire
file has been read.
This problem is on my list, with a lot of other Fortran / doxygen problems.

Albert


On Thu, Oct 10, 2013 at 12:13 PM, Jörg Sichermann <
joe...@fg...> wrote:

> Dear Albert,
>
> I see the same error running Doxygen 1.8.5
> I saw the date of our message ( year 2010 ) - Does exist a solution now?
>
> Best Regards,
> Joerg
>
>
>
> --
> View this message in context:
> http://doxygen.10944.n7.nabble.com/Problem-documenting-Fortran-include-file-tp3694p6325.html
> Sent from the Doxygen - Users mailing list archive at Nabble.com.
>
>
> ------------------------------------------------------------------------------
> October Webinars: Code for Performance
> Free Intel webinars can help you accelerate application performance.
> Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most
> from
> the latest Intel processors and coprocessors. See abstracts and register >
> http://pubads.g.doubleclick.net/gampad/clk?id=60134071&iu=/4140/ostg.clktrk
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>

Re: [Doxygen-users] Problem documenting Fortran include file

[Jörg S. <joe...@fg...>]

Dear Albert,

I see the same error running Doxygen 1.8.5
I saw the date of our message ( year 2010 ) - Does exist a solution now?

Best Regards, 
Joerg



--
View this message in context: http://doxygen.10944.n7.nabble.com/Problem-documenting-Fortran-include-file-tp3694p6325.html
Sent from the Doxygen - Users mailing list archive at Nabble.com.

Re: [Doxygen-users] Public and private parts in documentation

[Ron W. <ron...@gm...>]

On Sat, Oct 5, 2013 at 11:30 AM, <
dox...@li...> wrote:

> Date: Mon, 23 Sep 2013 17:33:50 +0200
> From: Yura Vishnevskiy <yur...@gm...>
> Subject: Re: [Doxygen-users] Public and private parts in documentation
>
> I have also another more general problem. My application itself is an
> interpreter for some script-like language (similar to Ruby). I would
> like to use Doxygen not only to document the internals in this
> interpreter but also to describe this mentioned script-like language in
> a way just like it is done in Ruby, i.e. information about core classes
> and their methods, modules, etc. is provided in the source files, where
> they are implemented. Thus, I would like to have in principle two
> independent layers (for the internals of the interpreter itself and for
> the language which it implements) of documentation in the same source
> files using Doxygen. What could the most optimal and elegant way to do
> this?
>

You could use the \internal directive to denote internals documentation and
the \cond directive for your language reference. Then in you Doxygen
configuration, you can control which group of sections is included in the
generated document.

Re: [Doxygen-users] Exceptions for processing between restrictive

[Ron W. <ron...@gm...>]

On Sat, Oct 5, 2013 at 11:30 AM, <
dox...@li...> wrote:

> Date: Tue, 24 Sep 2013 14:13:01 +0200
> From: Yura Vishnevskiy <yur...@gm...>
>

is there any possibility to force Doxygen to process a part of
> documentation which is in forbidden area between \cond and \endcond ?
> The problem is that I have private files mostly with documentation for
> internal usage (where all code surrounded by \cond and \endcond) and
> small portions of public documentation inside.
>

Include the section name from the \cond directive in the
ENABLED_SECTIONS<http://www.stack.nl/%7Edimitri/doxygen/manual/config.html#cfg_enabled_sections>option
of your Doxygen configuration.

Re: [Doxygen-users] Documentation<->source_code dependency issues

[Jan R. <jan...@co...>]

Hi Andy,


Has anyone come across the the issue of unwanted interdependency of documentation and source code releases when embedding documentation in source code?

By this I mean that my documentation is extracted from my RTL source code and the following sequence occurs:

1. My RTL is verified, released and frozen.  Prayers have been prayed, sacrifices offered up, and it is done.  No more changes.

2. I generate my documentation for the last time, using the frozen RTL as a source, and realise that there is a documentation error in that source.

The difficulty is to find a robust process that respects the integrity of the frozen RTL but allows me to make the necessary documentation update.

I can imagine some hacks, but does anyone have experience of a good process please?

Thanks for any suggestions,

Andy Betts
------------------
+33 6 12 19 49 03
skype: betts.crolles
www.icondasolutions.com<http://www.icondasolutions.com/>

I have not experienced full force of the frozen code, but I had something similar.
1) Can you have documentation in separate files such as .dox?
(That probably beats the intention of having comments/documentation with source code)

2) Can you apply a patch to the source code copy before processing documentation?
This way you typos could be fixed without a need to modify source, but any significant additions/deletions would mess the line numbering.
The fixes then can get to next release.

Jan

Re: [Doxygen-users] Presumed brief?

[Ron W. <ron...@gm...>]

On Mon, Oct 7, 2013 at 9:01 AM, <dox...@li...
> wrote:

> Date: Mon, 7 Oct 2013 09:01:21 -0400
> From: John Yates <jo...@ya...>
> Subject: Re: [Doxygen-users] Presumed brief?
>
> The problems seem to be:
> - handling of C++ /// (to my mind the least obtrusive markup) seems
> inconsistent with other comment syntaxes.
>

While I don't know why, the designed behavior, in Doxygen, for /// is to
require at least a 2 line comment block. This is mentioned in Doxygen's
documentation.

(This is in contrast to ///< which seems to work just fine as a single line
comment block.)


> - autobrief is very line oriented.  I cannot seem to get an autobrief to
> span more than a single line and end at the first period.
>

This has worked for me in the past, but seems to be broken, now. The
documentation examples imply this should work.


> - the new MULTILINE_CPP_IS_BRIEF tag makes everything up to the first
> paragraph break into an autobrief.
>

Maybe this new feature also changed the previous "until first ." behavior?


> I have looked at the doxygen source code.  I am not surprised at my
> difficulties.  Decomposition of a block into brief and detailed components
> is implemented in the lexer's state machine.  That state machine has to
> handle properly every one of the many supported syntaxes.  I would have
> though a better design would be to collect a block ignoring any notion of
> autobrief.  At the end, after all documentation for all symbols had been
> collected, if autobrief is enabled and if a given symbol lacked an explicit
> brief description then I would simply define the brief description to be
> the initial text up to the first period or paragraph break.
>

I agree. This seems a more sensible way to handle parsing of comment
blocks.

Re: [Doxygen-users] Using \todo in a similar way to \page

[Ron W. <ron...@gm...>]

On Mon, Oct 7, 2013 at 9:01 AM, <dox...@li...
> wrote:

> Date: Sun, 6 Oct 2013 19:09:00 +0800
> From: Andrew Stoeckley <and...@gm...>
>
> I like how you can put a \page tag anywhere, even an empty header file with
> nothing but doxygen comments, and use this to generate documentation.
>
> Unlike the \page tag, some other useful tags like \todo or the more generic
> \xrefitem, will not appear in documentation unless they are "attached" to
> source code, like a function definition. I have been getting around this by
>

You could create your own "To Do" page, though it would be separate from
the one generated generated by the \todo directive.

As for other directives, you can use "\par header" to get a similar output
in pages of your own construction. To simplify that, you can define aliases
in your Doxygen configuration that turn those \par constructions into
custom directives.

Re: [Doxygen-users] Presumed brief?

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

Hi John,

You can use MULTILINE_CPP_IS_BRIEF=YES and JAVADOC_AUTOBRIEF=NO 

/// A brief description that 
/// spans multiple lines.
///
/// More details follow.

or you can use MULTILINE_CPP_IS_BRIEF=NO and JAVADOC_AUTOBRIEF=YES

/// A brief description that 
/// spans multiple lines.
/// More details follow.

In the latter case you should always have at least 2 ///'s if you
want a detailed description. A single line with /// is always a brief
description.

I think this provides enough flexibility and I don't want to make things
even more complex.

Regards,
  Dimitri

On Oct 7, 2013, at 15:01 , John Yates <jo...@ya...> wrote:

> Greg,
> 
> Thanks for the reply.  (And thanks for correcting those typos in my final paragraph :-).
> 
> Yes, I am familiar with all three of those settings.  And today I actually get vaguely useful output from doxygen.
> 
> The problems seem to be:
> - handling of C++ /// (to my mind the least obtrusive markup) seems inconsistent with other comment syntaxes.
> - autobrief is very line oriented.  I cannot seem to get an autobrief to span more than a single line and end at the first period.
> - the new MULTILINE_CPP_IS_BRIEF tag makes everything up to the first paragraph break into an autobrief.
> 
> I have looked at the doxygen source code.  I am not surprised at my difficulties.  Decomposition of a block into brief and detailed components is implemented in the lexer's state machine.  That state machine has to handle properly every one of the many supported syntaxes.  I would have though a better design would be to collect a block ignoring any notion of autobrief.  At the end, after all documentation for all symbols had been collected, if autobrief is enabled and if a given symbol lacked an explicit brief description then I would simply define the brief description to be the initial text up to the first period or paragraph break.
> 
> /john
> 
> 
> On Mon, Oct 7, 2013 at 3:46 AM, Greg Aldridge <Gre...@do...> wrote:
> Without knowing what "various document control settings" you've experimented with it's difficult to make suggestions or guess how well you've read the manual (or even the comments in the default config file).
> 
> If you have read the manual (or comments) you'll already know about these:
> <http://www.stack.nl/~dimitri/doxygen/manual/config.html#cfg_javadoc_autobrief>
> <http://www.stack.nl/~dimitri/doxygen/manual/config.html#cfg_repeat_brief> &
> <http://www.stack.nl/~dimitri/doxygen/manual/config.html#cfg_always_detailed_sec>
> 
> Greg.
> 
> > -----Original Message-----
> > From: John Yates [mailto:jo...@ya...]
> > Sent: 05 October 2013 16:14
> > To: dox...@li...
> > Subject: [Doxygen-users] Presumed brief?
> >
> > Greatly influenced by emacs documentation conventions I strive for a
> > lightweight, prose-oriented methodology.  A crucial guiding principle is
> > DNRY (Do Not Repeat Yourself).  I never use mark up tokens (e.g. \brief,
> > \fn, \param, etc) because:
> > 1) they consume ridiculous amounts of precious vertical space
> > 2) they require repeating names already available from the source (violating
> > DNRY)
> > 3) they scream "marked up"
> >
> > My typical function looks like:
> >
> > int foo
> >     /// A sentence which constitutes a brief statement of the
> >     /// function's significance
> >     ( bool x    ///< A brief description
> >     , char y    ///< Another brief description
> >     , long z    ///< Yet another brief description
> >     )
> > {
> >     ...
> > }
> >
> > Often all I provide is a one line brief description of my function.
> > Sometimes it fits on one line; sometimes it does not.  Most times I remember
> > the final period; sometime I forget.
> >
> > Sometimes I amplify my description.  In such cases the first (brief
> > description) sentence definitely ends with a period (though not necessarily
> > on the first line).  The amplification is written as a logical continuation
> > of that brief description.  Hence when presenting a detailed description I
> > do not want to omit that introductory opening first sentence.
> >
> > What I would really like is for doxygen to assume that any documentation
> > block is at least a brief description.  If it contains no period or if a
> > period is not followed by additional text then there is only a brief
> > description and nothing more.  In such cases I would really like doxygen to
> > suppress its "More..." link rather than suggest incorrectly that more
> > documentation is available.
> >
> > If a documentation block contains a period followed by additional text
> > (whether or not that period falls on the first line) then I would like
> > doxygen to interpret the entire block from start to finish as a detailed
> > description.
> >
> > I have experimented with various doxygen contral setting attempting to
> > achieve this behavior.  As best as I can tell it is not possible to achieve
> > this behavior.  Am I correct?  Or have I missed something?
> >
> > /john
> >
> >
> >
> > --
> > View this message in context: http://doxygen.10944.n7.nabble.com/Presumed-
> > brief-tp6315.html
> > Sent from the Doxygen - Users mailing list archive at Nabble.com.
> >
> > ----------------------------------------------------------------------------
> > --
> > October Webinars: Code for Performance
> > Free Intel webinars can help you accelerate application performance.
> > Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most
> > from
> > the latest Intel processors and coprocessors. See abstracts and register >
> > http://pubads.g.doubleclick.net/gampad/clk?id=60134791&iu=/4140/ostg.clktrk
> > _______________________________________________
> > Doxygen-users mailing list
> > Dox...@li...
> > https://lists.sourceforge.net/lists/listinfo/doxygen-users
> 
> 
> ****************************************************
> Visit our website at http://www.domino-printing.com
> ****************************************************
> This Email and any files transmitted with it are intended only for the person or entity to which it is addressed and may contain confidential and/or privileged material. Any reading, redistribution, disclosure or other use of, or taking of any action in reliance upon, this information by persons or entities other than the intended recipient is prohibited.  If you are not the intended recipient please contact the sender immediately and delete the material from your computer.
> 
> E-mail may be susceptible to data corruption, interception, viruses and unauthorised amendment and Domino UK Limited does not accept liability for any such corruption, interception, viruses or amendment or their consequences.
> ****************************************************
> Domino UK Limited. Registered in England. Registered Number:1750201. Registered Office Address: Trafalgar Way, Bar Hill, Cambridge, CB23 8TU.
> 
> 
> 
> ------------------------------------------------------------------------------
> October Webinars: Code for Performance
> Free Intel webinars can help you accelerate application performance.
> Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most from
> the latest Intel processors and coprocessors. See abstracts and register >
> http://pubads.g.doubleclick.net/gampad/clk?id=60134791&iu=/4140/ostg.clktrk
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
> 
> ------------------------------------------------------------------------------
> October Webinars: Code for Performance
> Free Intel webinars can help you accelerate application performance.
> Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most from 
> the latest Intel processors and coprocessors. See abstracts and register >
> http://pubads.g.doubleclick.net/gampad/clk?id=60134791&iu=/4140/ostg.clktrk_______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users