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

[Dimitri v. H. <di...@st...>]

Hi Ian,

Thanks for the patch. It'll be included in the next CVS update.

Regards,
  Dimitri

On Thu, Aug 07, 2003 at 05:24:43PM +0100, Ian Scott wrote:
> 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.
>