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

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

On Thu, Jul 17, 2003 at 07:06:44PM +0100, Ian Scott wrote:
> First of all let me say thank-you to Dimitri and contributors for this
> wonderful program.
> 
> Our project (vxl.sf.net) uses Doxygen very heavily. We have started using
> the \relates option quite a lot in new code, like this:
> 
> my_func.h
> 
>     /** A simple function.
>      *  Detailed description
>      * \relates my_class
>      */
>     void my_func(my_class &);
> 
> my_class.h
> 
>     /** A simple class.
>      */
>     class my_class { };
> 
> Currently doxygen produces the documentation for my_func and puts it in the
> same page as the documentation for my_class. If the \relates were not there,
> then the documentation for my_func would go in the my_func.h page.
> 
> For various reasons we would like the documentation for my_func to appear in
> both the my_class page and the my_func.f page.
> 
> Firstly is there away of doing this at present? (Using \sa or something
> similar in the my_class comments is not suitable - we need a backwards
> reference in the my_func.h file)

No, doxygen internally maintains a list of all members with global/namespace
scope and a list of all class members. \relates put a member that actually
belongs to the first list in the second list. What you need is to put
the member in both lists.

> Secondly if not, would you accept a patch to provide such functionality
> (assuming it was well written etc.?)

Yes.

> Thirdly if you would accept a patch, how would like like this functionality
> to be used?
> 
> 1. Make it default behaviour for /relates in a function doc-comment to put
> the documentation for that function in both the file (my_func.h)
> documentation and the class documentation.
> 
> 2. Keep default behaviour as normal, but add an option to the control file
> that turns on behaviour as described above
> 
> 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.

The \relates command is detected in scanner.l and its argument is stored
in the "relates" member of an Entry. In doxygen.cpp there is a findMember()
function which contains code handling related members. I think the best
way to implement this is to keep the "relates" field, and add a "relatesDup"
boolean field to indicate if the member needs to be duplicated. If the
boolean is TRUE you need to create two new MemberDefs, one for each list.

Regards,
  Dimitri