doxygen-develop

[Doxygen-develop] Silent dropping of documentation

[Brendon C. <br...@ch...>]

If i use doxygen to generate documentation from the following code, it
does not perform a "union" of the two sets of documentation for the one
function and it also does not emit any warnings. It just uses the
documentation from the first block and ignores the second.

/** \brief Brief for function.
 *
 * Detail 1 for function.
 */
void MyFunction()
{
}

/** \fn MyFunction()
 * Detail 2 for function.
 */


I would have expected a union of the two blocks to have been achieved
where possible, otherwise at least a warning to have been emitted
indicating that the documentation from the second block is being discarded.

I would like to be able to perform a union of this documentation so that
if you look at the documentation for MyFunction you will see something like:

Brief for function.

Detail 1 for function.
Detail 2 for function.

Is there anything that can achieve this currently? Basically i have
additional documentation for every function that is automatically
generated by an external program that i want to include in addition to
the user defined documentation.

Is there anything existing in doxygen that will achieve this and if not
would anyone mind me trying to add something like this that works either
with the above \fn command or a new command specifically for that purpose?

Thanks,
Brendon.

Re: [Doxygen-develop] Silent dropping of documentation

[Dave D. <do...@do...>]

On Mon, Mar 26, 2007 at 09:18:33PM +1000, Brendon Costa wrote:
> I would like to be able to perform a union of this documentation so that
> if you look at the documentation for MyFunction you will see something like:
> 
> Brief for function.
> 
> Detail 1 for function.
> Detail 2 for function.

One thing to bear in mind is how you would tell Doxygen which detail
should come first in the unioned version.

> Is there anything that can achieve this currently?

Not trivially, I think.

> Basically i have additional documentation for every function that is
> automatically generated by an external program that i want to
> include in addition to the user defined documentation.

I haven't tried this, but you might be able to use \copydoc.  For
example have your generated documentation use slightly modified
function names so that Doxygen thinks the documentation is for some
other function, and then use \copydoc to bring that into the function
that it's really meant to be with.  I don't know if you can then stop
Doxygen from outputting the fake function in the final documentation,
though.

In the few cases where I need to programmatically generate the input
to Doxygen, I actually pre-process the code file itself.  For example
for one set of functions I have m4 macros to produce LaTeX pictures
which would be very tedious to type out and maintain by hand.  The
original code is in "foo.h.m4", and the Makefile automatically
generates "foo.h" from that as part of the build.  It's ugly, but it
does work.

                                                  -Dave Dodge

Re: [Doxygen-develop] Silent dropping of documentation

[Brendon C. <br...@ch...>]

Thanks for the info. In my situation the order of the documentation is
not overly important. With that said i would prefer it to take the order
to be such that the first documentation block encountered would be first
in the detailed section. This way if two documentation blocs are in the
same file it is easy to determine which goes first, and if you want to
do it between files well then it is important how you construct the
INPUT file list for the files to be scanned.

I just created a small patch to entry.cpp in the doxygen-1.5.1 source
which will append the detailed documentation from a new entry that is
being added to an existing entry if the two entries have the same name.

Thinking about it more it may be better for the entry to be added as it
is currently, but to modify the place in the doxygen source that makes
use of this list to generate the documentation. The m_sublist QList
contains the duplicates from my example, it just seems that whatever it
is that generates the documentation from this list only uses the first
item it finds of a given name and ignores the second.

If this does not work out, ill give the /copydoc command a try.

Thanks,
Brendon.


Dave Dodge wrote:
> On Mon, Mar 26, 2007 at 09:18:33PM +1000, Brendon Costa wrote:
>> I would like to be able to perform a union of this documentation so that
>> if you look at the documentation for MyFunction you will see something like:
>>
>> Brief for function.
>>
>> Detail 1 for function.
>> Detail 2 for function.
> 
> One thing to bear in mind is how you would tell Doxygen which detail
> should come first in the unioned version.
> 
>> Is there anything that can achieve this currently?
> 
> Not trivially, I think.
> 
>> Basically i have additional documentation for every function that is
>> automatically generated by an external program that i want to
>> include in addition to the user defined documentation.
> 
> I haven't tried this, but you might be able to use \copydoc.  For
> example have your generated documentation use slightly modified
> function names so that Doxygen thinks the documentation is for some
> other function, and then use \copydoc to bring that into the function
> that it's really meant to be with.  I don't know if you can then stop
> Doxygen from outputting the fake function in the final documentation,
> though.
> 
> In the few cases where I need to programmatically generate the input
> to Doxygen, I actually pre-process the code file itself.  For example
> for one set of functions I have m4 macros to produce LaTeX pictures
> which would be very tedious to type out and maintain by hand.  The
> original code is in "foo.h.m4", and the Makefile automatically
> generates "foo.h" from that as part of the build.  It's ugly, but it
> does work.
> 
>                                                   -Dave Dodge
> 
> 
> 
>