[Dune] Re: [Dune-CVS] CVS (burriad)

[Oliver Sander]

Hi!
In my humble opinion, in a perfect world there would be two Doxygen 
documentations.

- One for Dune developers.  Reading code sucks.  If there is
   a good doxygen documentation that includes all classes, files
   and methods it helps a lot.  In principle, such a documentation can be
   done easily by setting EXTRACT_ALL = YES in the Doxyfile

- One for Dune users.  This should contain only those classes etc.
   which is not for internal use only.

The problem is the following.  Even though EXTRACT_ALL = YES
shows all declarations, we want to further doxygen-document
(some of) them for Dune-developers, too.  This implies that
those classes (methods, etc.) also appear when EXTRACT_ALL
is set to NO.  There is support in Doxygen for finegrained
conditional documentation,  I do not know how usefull it
is, though.  In any case, choosing this approach means
more work.

Greetings,
Oliver

************************************************************************
* Oliver Sander                **                                      *
* Freie Universität Berlin     ** email: sander at math.fu-berlin.de      *
* Institut für Mathematik II   ** phone: + 49 (30) 838 75217           *
* Arnimallee 2-6               ** fax  : + 49 (30) 838 54977           *
* 14195 Berlin, Germany        ** URL  : www.math.fu-berlin.de/~sander *
************************************************************************

On Wed, 22 Dec 2004, Markus Blatt wrote:

> Hi,
>
> On Wed, Dec 22, 2004 at 11:24:50AM +0100, Adrian Burri wrote:
>> Update of /var/lib/cvs/dune/common/test
>> In directory hal:/tmp/cvs-serv18846/common/test
>>
>> Modified Files:
>> 	iteratorfacadetest.hh iteratortest.hh
>> Log Message:
>> Added comments so that (hopefully) every class appears in the documentation
>>
>
> why do you think that every class has to be in the doxygen
> documentation? As far as I understood the doxygen documentation is meant
> to help users using dune and should definitely not reveal internals of
> the implementation. Those interna should definitely be hidden to the
> user.
>
> I will just comment on my classes but I am quite sure this will transfer to
> nearly all classes you decorated with the doc me tag:
>
> poolallocator.hh The class Chunk (reresenting a chunk of memory can and
> should only used within the containing class. Nobody has an interest in
> how it is implemented, so it should be hidden to the user.
>
> typetraits.hh The typetraits use helper classes for convenient
> implementation. They are needed for the implementation but should never
> be used standalone, so they should not be documented.
>
> All test classes. They should also not appear in the doxygen
> documentation as they are of no interest to the user.
>
>
> Developers who want to change interna of an implementation will need
> more information than could ever be included in the documentation
> anyway. They need to know exactly who a class work and will have to read
> the source!!
>
> Cheers,
>
> Markus Blatt
> -- 
>
> _______________________________________________
> Dune mailing list
> Dune at hal.iwr.uni-heidelberg.de
> http://hal.iwr.uni-heidelberg.de/cgi-bin/mailman/listinfo/dune
>