Re: [Doxygen-develop] Proposal for extension to doxygen

[Ian S. <ian...@st...>]

Doxygeners,

I have implemented a /relatesalso command as discussed in previous emails.

The patches for the mods are included and implements as follows
cd $doxygen/src; patch <~/src.patch
cd $doxygen/doc; patch <~/doc.patch
cd $doxygen/examples; patch <~/examples.patch

I have made changes to the scanner - to detect the /relatesalso command.
As suggested I have added a relatesDup bool attribute to the Entry class.
This is set to true when the \relatesalso command is detected.

The MemberDef class has had an extra ClassDef *related_also attribute added.
This is currently used to indicate that normal global/file function
definition has been marked \relatesalso so that it doesn't get incorrectly
processed by transferRelatedFunctionDocumentation. However, in future it
could be used to provide a hyperlink from the global function documentation
to the documentation of the same function in the class, and maybe remove one
of the unnecessary full function documentation blocks.

The changes to doxygen.cpp have following effect:
1. Identify entries marked with relatesalso as both class and global
documentation in buildFunctionList and findMember
2. Don't mark the relatesalso entries EMPTY after processing by
buildFunctionList, so that it can be picked up by
transferRelatedFunctionDocumentation
3. Provide relevant debug information with the Debug:: approach.

I have also included relevant changes to the documentation and examples
files.

I have tested the code on our own code base (50 Mb source -> 167 Mb doxygen
produced html), and the existing examples in doxygen. The modified doxygen
produced identical html in both. I also replaced all the instances of
/relates with /relatesalso in own codebase. Doxygen ran with identical Log
output, and produced the desired html output in the cases I checked.

To encourage you to accept this patch, I should explain its usefulness.
Our codebase is a library for computer vision researchers consisting of a
large number of classes representing data, and an even larger number of
functions representing algorithms for the data. The algorithms are in files
and directories according to some categorisation. Lots of changes are made
to the algorithms, not so many to the classes. We would like users to have
two routes to finding any algorithm, through the class page to find the
algorithms that apply to that class, any through the file page to find
algorithms in a certain category. Using /relatesalso is a much cleaner
method of generating the necessary documentation, than say adding lots of
/sa to the class documentation every time an algorithm is changed.

Many thanks,

Ian Scott
VXL developer.


> Date: Mon, 21 Jul 2003 08:58:39 +0200
> From: Dimitri van Heesch <di...@st...>
>
> On Thu, Jul 17, 2003 at 07:06:44PM +0100, Ian Scott wrote:
> > ...
> > /relates also
> > Secondly if not, would you accept a patch to provide such
> functionality
> > (assuming it was well written etc.?)
>
> Yes.
>
> >
> > 3. Add a new special command (e.g. \relatesalso) that
> behaves as described
> > above.
>
> I would opt for number 3.
>
> > Forthly, have you any hints on how to implement it.
> >
> > We would find this functionality very useful, and have a
> small amount of
> > time to implement it - assuming it is relatively staightforward.
>