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
|
