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

[Thimo Neubauer]

Hello,

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!

Well, due to the Barton-Nackman-trick and the default implementations
the inheritance graph isn't as useful as in other software. Doxygen
can't really cope with templates andthus it's rather difficult to find
the correct methods anyway. I've assembled a small reference card our
students are currently beta-testing and will attach it to this
email. The two files are two different but still ugly versions :)

The doxygen-generated documentation can never suffice to learn Dune,
we still have to write high-level documentation for that. Each
"component/module" should still have a text in doxygen to describe the
general ideas but you can't possibly get the big picture.

Therefore we started the dune-tutorial featuring some simple and
highly documented examples. Unfortunately, even we have to guess the
interface and due to sparse docs in the functionspaces I'm quite sure
that laplace.cc is badly broken. However "projection.cc" and "ccfv.cc"
(cell centered finite volume) should provide you with good starting
points.

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

Could you investigate this a bit deeper? If it's a real problem we'd
be interested in fixing it.

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

First (and without shouting) let's differentiate: there is the code an
application-writer (aka the Dune-user) would like to know: the public
methods and the datastructures that do whatever he needs in an
efficient way. Then there is the
grid/functionspace/... implementer. He wants to know what methods he
needs to implement. And then there is the weird middle-layer which
is bound to vanish but eases the task of both aforementioned groups.

In my opinion the priority should be like this: we should document any
function for the application writers in doxygen because that's what
this software is best at: finding functions in a huge pile of sources.

The grid/functionspace/... implementer is only interested in a
specific part where doxygen would be interesting. But practically
speaking you'll be more interested in a working implementation which
is directly commented _in the code_. The parameters of each method
won't interest you that much as you're taking a working version
anyway. There is clearly a need to improve the comments in the
"reference implementations" but IMO that's totally unrelated to the
doxygen docs.

The middle-layer with wrapper-classes, repetitions of typedefs and
template-tricks should not appear in any public documentation! We all
know that users tend to find the wrong solutions when they do keyword
searches: when they find out about GridDefault and use it anywhere in
their code it won't do anything useful! Of course, inside the source
normal comments should tell what this is about. But nothing in Doxygen
please!

> - For users of Dune, there is IMHO no reason to hide anything from them. 

see above. We know that they don't want to see the full
complexity. You don't want to know the system-call number if you're
reading the documentation of fopen() either...

> What is more important to them is a useful set of examples that show how 
> to actually do something meaningful with the code.

That's why the dune-tutorial is mentioned in several places on the
Dune-Homepage.

Cheers
   Thimo
-------------- next part --------------
A non-text attachment was scrubbed...
Name: grid.ps.bz2
Type: application/octet-stream
Size: 428726 bytes
Desc: not available
URL: <https://lists.dune-project.org/pipermail/dune/attachments/20041222/38863739/attachment.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: grid_color.ps.bz2
Type: application/octet-stream
Size: 430391 bytes
Desc: not available
URL: <https://lists.dune-project.org/pipermail/dune/attachments/20041222/38863739/attachment-0001.obj>