[Dune] (no subject)

[Oliver Sander]

Hallo Adrian!
Mit EXTRACT_ALL hatte ich nie Probleme.  Wenn Du tote Links
bekommst muß es ein Fehler in Doxygen sein.

Aber:

Gerade wollte ich es noch mal mit meiner Version (1.3.9.1)
ausprobieren.  Und doxygen liefert einen Segfault wenn
man EXTRACT_ALL einstellt.

:-|

Grüße,
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, Adrian_Burri wrote:

> 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
>> 
>