[Doxygen-develop] doxygen and c++ templates, return types, alignment... (fwd)

[Michael L. <le...@ma...>]

Hello everybody,

I first was sending this eMail directly to Dimitri van Heesch I think it
was a bad idea (I am sorry) and hope that this mailing list is the right
place...

I am at the moment working on C++ library for numerical analysis
(http://sourceforge.net/projects/flens/). For the documentation we want to
use doxygen.  There's only a small problem that because of our heavy usage
of templates some things don't look as good as they could (IMO).  I made a
very small change in one of the doxygen sourcefiles to outline my idea and
would like to know your opinion about it...


The problem I see with the doxygen generated documentation is that
typenames in our library can become pretty long, like
 - MatrixReference<DenseMatrix<D> >
 - ListInitializerSwitch<flens::Matrix<typename Matrix::Data > >
 - ...

This makes the table for "Public Member Function" in a class documentation
kind of unreadable if one uses the format

   RETURN_TYPE   MEMBER_FUNCTION

where RETURN_TYPE is right aligned and MEMBER_FUNCTION is left aligned.
(e.g.: http://www.mathematik.uni-ulm.de/~lehn/flens/html/classflens_1_1MatrixReference.html)


My idea is to use 2 lines and the format

   RETURN_TYPE
   MEMBER_FUNCTION

both left-aligned.
(e.g.: http://www.mathematik.uni-ulm.de/~lehn/flens/html_modified/classflens_1_1MatrixReference.html)

I didn't have time to make myself more familiar with the doxygen source
code, but there two more things I thought about:

1) For the "Member Function Documentation" a format using 3 lines like

   CLASS_NAME
	RETURN_TYPE
        MEMBER_FUNCTION

would look good in my opinion.

2) Another problem seems to be caused by nested templates like:

   DenseMatrix<typename Promotion<VectorData, VectorData>::type >


what do you think about that in general?

thanks,
Michael