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

[Markus Blatt]

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

--