doxygen-users — List for users of doxygen

Re: [Doxygen-users] Presumed brief?

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

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
>

Re: [Doxygen-users] Presumed brief?

[Greg A. <Gre...@do...>]

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.

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

[Andrew S. <and...@gm...>]

Greetings,
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
just putting a "namespace foo{}" after all my \todo tags that I have in a
list I'm keeping track of, but is there a better way? I'd like more control
over raw generation of HTML pages without necessarily referencing specific
source code.

Andrew

[Doxygen-users] Presumed brief?

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

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.

[Doxygen-users] Complete call and caller graphs

[Tarcísio R. <tar...@gm...>]

Hello there.

I was trying to get doxygen to generate the complete call and caller graphs
for a project of mine. I have all the things setup and it indeed generates
such graphs for all the functions on code, although not the complete ones.

The documentation specify this behaviour, saying it truncates the graphs in
order to try to make them fit in 1024 pixels.

Is there a way to prevent it from doing this, say, for just one function or
another?


Thanks in advance,

Tarcísio G. Rodrigues

[Doxygen-users] Extern variable appears twice, leading to errors in docbook generation

[ADuering <And...@tn...>]

Hello doxygen mailing list,

I'm generating my source code documentation with doxygen 1.8.5, outputting
it as docbook. When processing this with xsltproc, I get the following error
messages.

>xsltproc --xinclude --output myfile.filt.xml
stylesheets\docbook-xsl-ns-1.78.1\profiling\profile.xsl index.xml
a00257.xml:4721: element section: validity error : ID
a00257_1ga813ffb0c0476e2df0c0a781a6dc842a8 already defined
            <section xml:id="a00257_1ga813ffb0c0476e2df0c0a781a6dc842a8">
                                                                        ^
a00288.xml:657: element section: validity error : ID
a00288_1gab608b7cc1a21932f503543f016afb200 already defined
            <section xml:id="a00288_1gab608b7cc1a21932f503543f016afb200">
                                                                        ^
a00288.xml:661: element section: validity error : ID
a00288_1ga8b04c96b2bb53dc5543042564ad114b4 already defined
            <section xml:id="a00288_1ga8b04c96b2bb53dc5543042564ad114b4">
                                                                        ^
a00288.xml:665: element section: validity error : ID
a00288_1ga42b979d814d70492577d266e4e36958f already defined
            <section xml:id="a00288_1ga42b979d814d70492577d266e4e36958f">
                                                                        ^
a00288.xml:669: element section: validity error : ID
a00288_1gaac45095a095b6830d1e6d2968224d827 already defined
            <section xml:id="a00288_1gaac45095a095b6830d1e6d2968224d827">
                                                                        ^
a00288.xml:673: element section: validity error : ID
a00288_1gab733495c49e00065c7e972f835b19962 already defined
            <section xml:id="a00288_1gab733495c49e00065c7e972f835b19962">

Looking in the mentioned files reveals the variables which cause this error.
(For some reason, they seem to be discovered twice... Indeed, 
            <section xml:id="a00257_1ga813ffb0c0476e2df0c0a781a6dc842a8">
                <title>TYPE_S_DATA Data</title> <emphasis></emphasis>
            </section>
appears twice in that file)

Furthermore, If I generate HTML documentation, and enter the variable name
in the search bar (SEARCHENGINE being set to YES), the variable also appears
twice as defined, in the same location. So basically the Html documentation
says

TYPE_S_DATA Data
Definition at line 123 of file filename.c.

TYPE_S_DATA Data
Definition at line 123 of file filename.c.

This variabe is a global variable in a C file, which then is extern'd by the
.h file.
(So the .h file contains "extern TYPE_S_DATA Data;")

Does this duplicate result from the variable being extern'd? Or is there
another reason for this strange behaviour?

Best regards,
ADuering

Doxgen Config:
doxy.cfg <http://doxygen.10944.n7.nabble.com/file/n6301/doxy.cfg>  



--
View this message in context: http://doxygen.10944.n7.nabble.com/Extern-variable-appears-twice-leading-to-errors-in-docbook-generation-tp6301.html
Sent from the Doxygen - Users mailing list archive at Nabble.com.

[Doxygen-users] Missing search terms in SEARCHDATA_FILE

[Amos A. <amo...@pr...>]

Hello Doxygen --

I'm using doxygen's tools for generating the XML file with SEARCHDATA_FILE. I'm using EXTERNAL_SEARCH=YES and SERVER_BASED_SEARCH=YES. This is all working great! Thanks for this very useful feature. However, I'm noticing that text inside of \c or \code is not appearing in the XML search file.


For example, my documentation page has this:
\par
...
For example, the \c -msaBias flag tells...

but I only see this in the XML file:
<field name="text">...For example the flag tells...</field>


so my search box is missing some hits. Is there a way I can make this text searchable?

Thanks!
Amos.

[Doxygen-users] Exceptions for processing between restrictive \cond and \endcond

[Yura V. <yur...@gm...>]

Hi All,
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.

Regards,
Yura

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

[Andrew B. <and...@ic...>]

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
------------------

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

[Yura V. <yur...@gm...>]

Dear André and Sebastien,
thank you for suggestions, they should work for me.

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?

Regards,
Yura


On 09/23/2013 05:04 PM, Sebastien Loriot wrote:
> On 09/23/2013 04:45 PM, Yura V. Vishnevskiy wrote:
>> Hello Doxygen Users and Developers,
> Hello,
>
>> my code contains different documented parts, some of them are just for
>> internal in-house usage, others are public. Both types can be in the same
>> source files. I am trying to figure out whether it is possible to create
>> somehow two different Doxygen config files so that with one I can generate
>> complete documentation and with other just the public parts. Is this
>> possible?
> I see at least three ways to do this:
> - using \internal
> http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdinternal
> - using \cond
> http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdcond
> - using the preprocessor
> http://www.stack.nl/~dimitri/doxygen/manual/preprocessing.html
>
> Sebastien.
>
>> Thanks in advance,
>> Yura Vishnevskiy
>>
>>
>>
>> --
>> View this message in context: http://doxygen.10944.n7.nabble.com/Public-and-private-parts-in-documentation-tp6290.html
>> Sent from the Doxygen - Users mailing list archive at Nabble.com.
>>
>> ------------------------------------------------------------------------------
>> LIMITED TIME SALE - Full Year of Microsoft Training For Just $49.99!
>> 1,500+ hours of tutorials including VisualStudio 2012, Windows 8, SharePoint
>> 2013, SQL 2012, MVC 4, more. BEST VALUE: New Multi-Library Power Pack includes
>> Mobile, Cloud, Java, and UX Design. Lowest price ever! Ends 9/20/13.
>> http://pubads.g.doubleclick.net/gampad/clk?id=58041151&iu=/4140/ostg.clktrk
>> _______________________________________________
>> Doxygen-users mailing list
>> Dox...@li...
>> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>
> ------------------------------------------------------------------------------
> LIMITED TIME SALE - Full Year of Microsoft Training For Just $49.99!
> 1,500+ hours of tutorials including VisualStudio 2012, Windows 8, SharePoint
> 2013, SQL 2012, MVC 4, more. BEST VALUE: New Multi-Library Power Pack includes
> Mobile, Cloud, Java, and UX Design. Lowest price ever! Ends 9/20/13.
> http://pubads.g.doubleclick.net/gampad/clk?id=58041151&iu=/4140/ostg.clktrk
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users

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

[André G. <and...@bi...>]

Hello,

did you check the /if/ command?
http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdif

Regards,
André

On 23-09-2013 15:45, Yura V. Vishnevskiy wrote:
> Hello Doxygen Users and Developers,
> my code contains different documented parts, some of them are just for
> internal in-house usage, others are public. Both types can be in the same
> source files. I am trying to figure out whether it is possible to create
> somehow two different Doxygen config files so that with one I can generate
> complete documentation and with other just the public parts. Is this
> possible?
>
> Thanks in advance,
> Yura Vishnevskiy
>
>
>
> --
> View this message in context: http://doxygen.10944.n7.nabble.com/Public-and-private-parts-in-documentation-tp6290.html
> Sent from the Doxygen - Users mailing list archive at Nabble.com.
>
> ------------------------------------------------------------------------------
> LIMITED TIME SALE - Full Year of Microsoft Training For Just $49.99!
> 1,500+ hours of tutorials including VisualStudio 2012, Windows 8, SharePoint
> 2013, SQL 2012, MVC 4, more. BEST VALUE: New Multi-Library Power Pack includes
> Mobile, Cloud, Java, and UX Design. Lowest price ever! Ends 9/20/13.
> http://pubads.g.doubleclick.net/gampad/clk?id=58041151&iu=/4140/ostg.clktrk
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users

-- 

*André Glória*
Embedded Systems Developer


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

*Bithium ® S.A.* . Av. Miguel Bombarda, 129 R/C . 1050-154 Lisboa . Portugal
*Phone* +351 21 3304224 . *Fax* +351 21 3304225 . *Web* 
http://www.bithium.com . *Skype* /bithium/

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

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

[Sebastien L. <slo...@gm...>]

On 09/23/2013 04:45 PM, Yura V. Vishnevskiy wrote:
> Hello Doxygen Users and Developers,
Hello,

> my code contains different documented parts, some of them are just for
> internal in-house usage, others are public. Both types can be in the same
> source files. I am trying to figure out whether it is possible to create
> somehow two different Doxygen config files so that with one I can generate
> complete documentation and with other just the public parts. Is this
> possible?
I see at least three ways to do this:
- using \internal 
http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdinternal
- using \cond 
http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdcond
- using the preprocessor 
http://www.stack.nl/~dimitri/doxygen/manual/preprocessing.html

Sebastien.

>
> Thanks in advance,
> Yura Vishnevskiy
>
>
>
> --
> View this message in context: http://doxygen.10944.n7.nabble.com/Public-and-private-parts-in-documentation-tp6290.html
> Sent from the Doxygen - Users mailing list archive at Nabble.com.
>
> ------------------------------------------------------------------------------
> LIMITED TIME SALE - Full Year of Microsoft Training For Just $49.99!
> 1,500+ hours of tutorials including VisualStudio 2012, Windows 8, SharePoint
> 2013, SQL 2012, MVC 4, more. BEST VALUE: New Multi-Library Power Pack includes
> Mobile, Cloud, Java, and UX Design. Lowest price ever! Ends 9/20/13.
> http://pubads.g.doubleclick.net/gampad/clk?id=58041151&iu=/4140/ostg.clktrk
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users

[Doxygen-users] Public and private parts in documentation

[Yura V. V. <yur...@gm...>]

Hello Doxygen Users and Developers,
my code contains different documented parts, some of them are just for
internal in-house usage, others are public. Both types can be in the same
source files. I am trying to figure out whether it is possible to create
somehow two different Doxygen config files so that with one I can generate
complete documentation and with other just the public parts. Is this
possible?

Thanks in advance,
Yura Vishnevskiy



--
View this message in context: http://doxygen.10944.n7.nabble.com/Public-and-private-parts-in-documentation-tp6290.html
Sent from the Doxygen - Users mailing list archive at Nabble.com.

Re: [Doxygen-users] Warning of mismatched arguments

[<mic...@th...>]

Could it be that the @param shows type "SlipDatum&" while the @fn shows type of that arg as "const SlipDatum&", so the type doesn't match up?   Just guessing, but...

From: Arthur Schwarz [mailto:asc...@at...]
Sent: Sunday, September 22, 2013 2:05 PM
To: dox...@li...
Subject: [Doxygen-users] Warning of mismatched arguments

I can't figure out what is wrong with the following:

 /**
 * @fn virtual SlipDatum& SlipOp::copy(const SlipDatum& X) const
 * @copydoc SlipDatum::copy()
 * @see SlipDatum::copy()
 * @param[in] X (SlipDatum&) cell to be copied
 */

and

      virtual SlipDatum& copy(const SlipDatum& X) const;

The code compiles and executes, so the code is ok. The message is:

SlipOp.h:707: warning: argument 'SlipDatum' of command @param is not found in the argument list of SlipOp::copy(const SlipDatum &X) const

The error cascades to all functions which override the virtual function. The @copydoc object has no argument and a @param statement is supplied here to account for the added argument. However most of the methods in this class have the same issue, the @copydoc object has one fewer argument than the implementation in this class, but there is no diagnostic message issued.

Have I done something wrong?

This email was sent to you by Thomson Reuters, the global news and information company. Any views expressed in this message are those of the individual sender, except where the sender specifically states them to be the views of Thomson Reuters.

Re: [Doxygen-users] Error: dot: can't open

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

Dear Arthur,

Where did you install graphviz, under Windows or Cygwin?
Looks to me like running a Windows version of dot / graphviz instead of a
Cygwin version or running a Windows version of doxygen under Cygwin.

Albert


On Sun, Sep 22, 2013 at 9:13 PM, Arthur Schwarz <asc...@at...>wrote:

> I have graphviz installed and a brief look in the browser seems to show no
> problem with the generated HTML. Any idea what these errors mean and how I
> can fix the problem?
>
> The files exist and the permissions are "-rw-r--r--", the sticky bit is
> not set and the owner has read/write permission. I'm the owner. There are
> about 109 like minded errors.
>
> Error: dot: can't open
> /cygdrive/e/home/skidmarks/Projects/SLIP/DOC/ReferenceManual/ReferenceManual/d7/d7a/_slip_cell_8h__dep__incl.dot
>
> error: Problems running dot: exit code=2, command='dot',
> arguments='"/cygdrive/e/home/skidmarks/Projects/SLIP/DOC/ReferenceManual/ReferenceManual/d0/d66/_slip_bool_op_8h__dep__incl.dot"
> -Tpng -o
> "/cygdrive/e/home/skidmarks/Projects/SLIP/DOC/ReferenceManual/ReferenceManual/d0/d66/_slip_bool_op_8h__dep__incl.png"'
>
>
>
> ------------------------------------------------------------------------------
> LIMITED TIME SALE - Full Year of Microsoft Training For Just $49.99!
> 1,500+ hours of tutorials including VisualStudio 2012, Windows 8,
> SharePoint
> 2013, SQL 2012, MVC 4, more. BEST VALUE: New Multi-Library Power Pack
> includes
> Mobile, Cloud, Java, and UX Design. Lowest price ever! Ends 9/22/13.
> http://pubads.g.doubleclick.net/gampad/clk?id=64545871&iu=/4140/ostg.clktrk
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>
>

[Doxygen-users] Error: dot: can't open

[Arthur S. <asc...@at...>]

I have graphviz installed and a brief look in the browser seems to show no problem with the generated HTML. Any idea what these errors mean and how I can fix the problem?

The files exist and the permissions are "-rw-r--r--", the sticky bit is not set and the owner has read/write permission. I'm the owner. There are about 109 like minded errors.

Error: dot: can't open /cygdrive/e/home/skidmarks/Projects/SLIP/DOC/ReferenceManual/ReferenceManual/d7/d7a/_slip_cell_8h__dep__incl.dot

error: Problems running dot: exit code=2, command='dot', arguments='"/cygdrive/e/home/skidmarks/Projects/SLIP/DOC/ReferenceManual/ReferenceManual/d0/d66/_slip_bool_op_8h__dep__incl.dot" -Tpng -o "/cygdrive/e/home/skidmarks/Projects/SLIP/DOC/ReferenceManual/ReferenceManual/d0/d66/_slip_bool_op_8h__dep__incl.png"'

[Doxygen-users] Warning of mismatched arguments

[Arthur S. <asc...@at...>]

I can't figure out what is wrong with the following:

 /** 
 * @fn virtual SlipDatum& SlipOp::copy(const SlipDatum& X) const
 * @copydoc SlipDatum::copy()
 * @see SlipDatum::copy()
 * @param[in] X (SlipDatum&) cell to be copied
 */

and

      virtual SlipDatum& copy(const SlipDatum& X) const;  


The code compiles and executes, so the code is ok. The message is:

SlipOp.h:707: warning: argument 'SlipDatum' of command @param is not found in the argument list of SlipOp::copy(const SlipDatum &X) const


The error cascades to all functions which override the virtual function. The @copydoc object has no argument and a @param statement is supplied here to account for the added argument. However most of the methods in this class have the same issue, the @copydoc object has one fewer argument than the implementation in this class, but there is no diagnostic message issued.


Have I done something wrong?

[Doxygen-users] Sort of warning messages by line number

[Arthur S. <asc...@at...>]

Is there an option to sort warning messages by line numbers for a file? It looks like each pass which generates a warning message outputs the message at the end of the previous last message in a file.

As always, great work.

thanks 

art

[Doxygen-users] <b> and</b> warning line number ambiguity

[Arthur S. <asc...@at...>]

Could you consider making the output line numbers for <b> and </b> warnings less ambiguous in your next software release? I've noted the following issues in the warning messages:
1: missing </b>. The line number is never correct. Most often it is a random number greater 

    than the last line of the file. If there are more than one missing </b> warnings in the file, 

    then each warning contains a line number greater than the previous one.
2: missing <b>. The line numbers are often correct (indicating where the </b> was found)
    but just as often incorrect.

And could you flag nested <b> blocks with a warning, as in <b>text<b> <b>text</b>?

For 1: above, it would be nice to issue a message which shows the line number of the
unmatched <b> tag.

For 2: above, it would be nice to always output the address of the detected </b>.

And for the nested <b> blocks, it would be nice to output the line number of each
nested <b> found.

As always, great work. 


Thanks
art

[Doxygen-users] Error with generating RTF from Doxygen 1.8.5

[Clint F. <cdr...@gm...>]

Anyone know why I get the below errors from Doxygen when trying to produce
doc from C# code?

error: problems opening rtf file namespaces.rtf for reading

error: An error occurred during post-processing the RTF files!

*** Doxygen has finished


I looked in the output directory and there is no file named
"namespaces.rtf".

There are namespace files like "namespace_xyz.rtf" though.


Thanks,
CF

[Doxygen-users] Wide image and tableofcontents at the beginning of a page

[Vaclav P. <wen...@gm...>]

Hi,

I've noticed that if I put wide image at the begining of the page and I
have also @tableofcontents fo the page, the image (and all the text after
it) is shown after the table of contents. So, with the long table of
contents you see a lot of empty space.

What is the best practice in this case? I can make the image smaller but
what is smaller actually depends on the screen where you browse the
documentation. Is there some Doxygen requirement to assumption for the
minimal screen width which I can use to determine the maximum image width?

Putting the picture as close to the bottom as possible might be the safest
way. Or is there some possibility to do foldable or overlaid table of
contents (or plan to include it)?

Vaclav


PS: I've noticed that I posted the email "Documentation for functions with"
with the wrong subject. I'm sorry about that. The email body should be
clear, its about support of function declaration styles.

[Doxygen-users] Documentation for functions with

[Vaclav P. <wen...@gm...>]

Hi,


I have a C code where function return type is on separate line:


int
Read_file(const char *name)


This function does not show in Doxygen documentation. It does not have a
doxyen comment but other functions without the comment are in
documentation. Moreover, when I change the function declaration/definition
to one line


int Read_file(const char *name)

it is included in documentation. So, I think my Doxyfile is correct.


Is this a known issue?

Thanks,
Vaclav

[Doxygen-users] How to configure line-indent while using @dontinclude or @snippet

[<Eck...@t-...>]

Hello Everybody.

I use the commands @dontinclude or @snippet to insert source-examples 
into my documentation. This examples are greater sources in c, python or 
other programming-languages or parts of xml-files. The original texts 
contain a lot of indented lines what means most of the original lines 
contain more than one spaces at the beginning. But in my html-output of 
Doxygen the indention is not shown. If I use @verbinclude the original 
source format is used but unfortunately  @verbinclude supports not to 
include only parts of the text.

If you take a look to the example of @dontinclude  in the documentation 
of Doxygen (1.8.5) you will see the same effect. If you compare the 
indention of the used source to include with the included lines you will 
see there is no indention in the included lines. Thus It may be a bug.

I know that in earlier versions of Doxygen @dontinclude was able to show 
the original  indention of the included text. For example if I use 
Doxygen 1.4.x it works but since some releases I'm not able to show the 
original indention any more.

What is my mistake? Is there a parameter I have to use now? Is there 
something in the configuration-file I have to configure?

Best regards,
                     Eckard Klotz.

Re: [Doxygen-users] Apple's NS_ENUM Macro

[Tom U. <to...@io...>]

Hi Marshall,

I believe you might be able to use something like

PREDEFINED             = "NS_ENUM ( ret_t, enumName )= enum enumName"

to get you into the ballpark.  It won't quite be the same as the hand 
coded C, but I think it is plausible you could at least get the right name.

Best regards,

Tom


> Folks,
>
> I have a file with a bunch of typedefs.
>
> I'm using Apple's recommended method of defining a NS_ENUM macro to
> declare enumeration typedefs.
>
> Normally, I'd define a typedef like so:
>
> typedef enum
> {
> MyCoolEnum_Value1= 1,
> MyCoolEnum_Value2= 2
> } MyCoolEnum;
>
> However, Apple (Objective C 2.0, really) has created a macro that allows
> you to assign a datatype to the enum, like so:
>
> typedef NS_ENUM ( uInt_16, MyCoolEnum )
> {
> MyCoolEnum_Value1= 1,
> MyCoolEnum_Value2= 2
> };
>
> Unfortunately, when Doxygen hits this, it sets the enum as "NS_ENUM",
> instead of "MyCoolEnum".
>
> Is there any way for me to get Doxygen to recognize the enum, or should
> I discard the Apple method, and use the plain old-fashioned C++ enum?
>
>
>
>
> _CONFIDENTIAL:_
> This e-mail including any attachments is intended only for the party or
> parties to whom it is addressed and may contain information which is
> privileged and/or confidential. If you are not the intended recipient,
> you are hereby notified that any use, disclosure, dissemination,
> distribution, copying, or printing of any information contained in or
> attached to this e-mail is STRICTLY PROHIBITED and may constitute a
> breach of confidentiality and/or privilege. If you have received this
> e-mail in error, please notify immediately the sender by reply e-mail
> and then delete this e-mail and any attachments in their entirety from
> your system. Thank you. This e-mail message including any attachments is
> believed to be free of any viruses; however, it is the sole
> responsibility of the recipient to ensure that it is virus free, and
> Nikon does not accept any responsibility for any loss, disruption or
> damage to your data or computer system which may occur in connection
> with this e-mail including any attachments.
>
> 	
> *Christopher D Marshall*
> Sr. Software Development Manager
> Nikon Inc.
> 1300 Walt Whitman Road
> Melville NY 11747-3064
> Office: 631-547-4334 	Fax: 631-547-0361
> 	
> cma...@ni... <mailto:cma...@ni...> 	
>
> www.nikonusa.com
>
> 	
>
>
> <http://www.nikonusa.com/en/Nikon-Products/Product/Compact-Digital-Cameras/26423/COOLPIX-A.html?cid=eml-0613-coolpixa-signature>
>
>
>
>
>
>
> ------------------------------------------------------------------------------
> LIMITED TIME SALE - Full Year of Microsoft Training For Just $49.99!
> 1,500+ hours of tutorials including VisualStudio 2012, Windows 8, SharePoint
> 2013, SQL 2012, MVC 4, more. BEST VALUE: New Multi-Library Power Pack includes
> Mobile, Cloud, Java, and UX Design. Lowest price ever! Ends 9/20/13.
> http://pubads.g.doubleclick.net/gampad/clk?id=58041151&iu=/4140/ostg.clktrk
>
>
>
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>

Re: [Doxygen-users] Apple's NS_ENUM Macro

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

Hi Christopher,

On Sep 17, 2013, at 21:02 , Marshall Christopher D. <cma...@ni...> wrote:
> Folks,
> 
> I have a file with a bunch of typedefs.
> 
> I'm using Apple's recommended method of defining a NS_ENUM macro to declare enumeration typedefs.
> 
> Normally, I'd define a typedef like so:
> 
> typedef enum
> {
> MyCoolEnum_Value1
> = 1,
> MyCoolEnum_Value2
> = 2
> } MyCoolEnum;
> 
> However, Apple (Objective C 2.0, really) has created a macro that allows you to assign a datatype to the enum, like so:
> 
> typedef NS_ENUM ( uInt_16, MyCoolEnum )
> {
> MyCoolEnum_Value1
> = 1,
> MyCoolEnum_Value2
> = 2
> };
> 
> Unfortunately, when Doxygen hits this, it sets the enum as "NS_ENUM", instead of "MyCoolEnum".
> 
> Is there any way for me to get Doxygen to recognize the enum, or should I discard the Apple method, and use the plain old-fashioned C++ enum?
> 

You can program doxygen's C-preprocessor to replace NS_ENUM, like so

ENABLE_PREPROCESSING   = YES
MACRO_EXPANSION        = YES
EXPAND_ONLY_PREDEF     = YES
PREDEFINED             = NS_ENUM(x,y)=y

Regards,
  Dimitri