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

[Adrian_Burri]

Hi,

as the one causing the stirr, here the reasons why I did this:
- I'm trying to get a grip on the code as a developer and it sucks 
trying to figure out how something works when the inheritance graph is 
not complete because classes in it are not documented!
- I tried the EXTRACT_ALL flag, but somehow (might be an old version of 
doxygen or my own stupidity) the undocumented classes would appear in 
the overview, but produce only a broken link when clicking on their entry.

This was the practical approach to the problem, now the philosophical one:
- There should be NO UNDOCUMENTED CODE! Not even, or rather: especially 
not, the code intended for developers only.  I don't intend to read 
through hundreds of lines of code to figure out what a method does. 
Intention, preconditions and postconditions should be clearly stated on 
every (public) method.
- For users of Dune, there is IMHO no reason to hide anything from them. 
What is more important to them is a useful set of examples that show how 
to actually do something meaningful with the code.

I hope this clarifies my point of view without leading to a flame war.

Cheers

Adi

Oliver Sander schrieb:

> 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
>
>
>> http://hal.iwr.uni-heidelberg.de/cgi-bin/mailman/listinfo/duneve to 
>> read to n Gentoo)     id 1Ch4dE-0002Tc-Oi; Wed, 22 Dec 2004 12:26:25 
>> +0100 Received: from mail.iwr.uni-heidelberg.de 
>> (mail.iwr.uni-heidelberg.de [129.206.104.30])     by 
>> relay2.uni-heidelberg.de (8.12.10/8.12.10) with ESMTP id 
>> iBMBQSbY024449;     Wed, 22 Dec 2004 12:26:29 +0100 (MET) Received: 
>> from hal.iwr.uni-heidelberg.de (mail at hal.iwr.uni-heidelberg.de 
>> [129.206.69.248])     by mail.iwr.uni-heidelberg.de (8.12.11/8.12.11) 
>> with ESMTP id iBMBQ5BG020334;     Wed, 22 Dec 2004 12:26:05 +0100 
>> (MET) Received: from localhost     ([127.0.0.1] 
>> helo=hal.iwr.uni-heidelberg.de ident=list)     by 
>> hal.iwr.uni-heidelberg.de with esmtp (Exim 3.35 #1 (Debian))     id 
>> 1Ch4d0-0005QW-00; Wed, 22 Dec 2004 12:26:02 +0100 Received: from 
>> mail.iwr.uni-heidelberg.de ([129.206.104.30])     by 
>> hal.iwr.uni-heidelberg.de with esmtp (Exim 3.35 #1 (Debian))     id 
>> 1Ch4cl-0005Q3-00     for <dune at hal.iwr.uni-heidelberg.de>; Wed, 22 
>> Dec 2004 12:25:47 +0100 Received: from relay2.uni-heidelberg.de 
>> (relay2.uni-hq
>