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

[Adrian_Burri]

Agreed on the tests. But the rest I really don't mind having them in the 
documentation. I don't need to read them, if I decide not to. But in 
case I change my mind, it's nice seeing all of it.

Adi

Markus Blatt schrieb:

>On Wed, Dec 22, 2004 at 01:15:57PM +0100, Adrian_Burri wrote:
>  
>
>>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!
>>    
>>
>
>The inheritance graph will never ever be complete because we use
>templates. So template specializations will never be seen in an
>inheritance graph.
>Especially if you want to get a grip on using the code (not changing it!) 
>you do not to want to be bothered with nested private classes (as is the
>case Pool::Chunk, Pool::Reference). Those can only be used from within
>Pool. By the way the documentation here will not show up as they are
>private.
>
>And why do you want to have the tests in the doxygen documentation is
>beyond me.
>
>  
>
>>- I tried the EXTRACT_ALL flag, [...]
>>    
>>
>
>  
>
>>This was the practical approach to the problem, now the philosophical one:
>>- There should be NO UNDOCUMENTED CODE! 
>>    
>>
>
>I agree with that. But people that want to use your Code (again not
>change it!), do not want to be bothered with helper templates
>(typetraits.hh).
>
>  
>
>>Not even, or rather: especially 
>>not, the code intended for developers only.  
>>    
>>
>
>Again one has to distinguish between developers using classes and
>developers changing classes. 
>
>The first are actually users of the written
>classes and only want to see public methods and classes, not the one
>used for internals to bypass shortcomings of the language (like it is is
>case for the template helper classes and template specializations).
>Especially when using the index it is quite disturbing to be bothered by
>classes and methods not intented for noninternal use.
>
>The latter are those that want to change the internals of
>class/algorithm. As they directly work in the same source file they can
>read thr nondoxygen documentation directly are guess by the
>selfdescribing names (Chunk and Reference should be quite clear and
>helper template classes and template specializations too).
>
>  
>
>>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.
>>    
>>
>
>Stress here is on public! So why did you introduce the doc me tag for
>nonpublic / internal (nested) classes in contradiction to your opinion?
>
>Maybe you got me wrong or I did not make my postion clear enough. I did
>not say that everyone has to read the source for using classes. As you
>said every method and class for public use should be documented (and
>hopefully is my code). But internal helper classes (like template
>specialization or private nested classes) should IMHO never appear in a
>doxygen documentation.
>
>  
>
>>- For users of Dune, there is IMHO no reason to hide anything from them. 
>>    
>>
>
>I disagree and as a look into the changes of typetraits.hh told me you
>actually do, too, as you did not say that the ConstVolatileTraits have
>to be documented.
>
>Cheers,
>
>Markus
>
>  
>