[Doxygen-develop] Proposal for extension to doxygen

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

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)

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

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.

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.

Many thanks,

Ian Scott.