fenics team mailing list archive

[kent-and@xxxxxxxxx]

>
>
> On 17/03/10 22:04, Johan Hake wrote:
>> Nice effort!
>>
>> I like the choice of bundle the documentation into one FEniCS
>> documentation,
>> and letting the existing documentation of the sub-projects be
>> Appendices, or
>> just incorporated into the new one.
>>
>> I agree with Marie that we also need a programmers reference, which is
>> more or
>> less the Doxygen generated code we have today (where is this online
>> btw?). As
>> such it is nice but the minimalistic approach to the C++ comments for
>> many
>> member functions makes the documentation a bit sparse. André has taken a
>> more
>> verbose approach when he documented the methods in IntersectionOperator.
>> The
>> code looks a bit cluttered (using /* */ instead of // on each line would
>> probably improve this), but it generates more verbose documentation.
>>
>> If we decides to be more verbose, which I think we should, we need to
>> define a
>> common way to do this. I kind of like how PETSc does it.
>>
>
> Personally, I dislike the (overly) verbose approach in the code since I
> often can't find the actual code amongst all the comments. I think that
> we do a pretty good job in DOLFIN on the C++ side of having most
> functions perform one simple task, which makes the function name +
> argument list + comment enough to describe what's going. Python involves
> more magic and there is no type information, so more elaborate doc
> strings are helpful.
>
>> We have also discussed using a standard format for the Python
>> Docstrings. So
>> nice programmers references can be generated from these. We haven't
>> decided
>> which one we are going to use (epydoc or others). I couldn't find
>> doconce (too
>> close to many other meanings of doc once :P) at the net so I do not know
>> what
>> this software does or how well adapted it is.
>>
>> Can someone(tm) explain what "well documented demos" means? Should the
>> equation the demo solve be explained more?
>
> Firstly, to document better the equation and the solution method. Then,
> to make clear how each 'step' in the solution process can be implemented.
>
>> Should an underlying structure a
>> demo show be explained in more detail (for example: one demo explaining
>> the
>> mixed method, and an other one explaining mesh refining, or the use of
>> JIT
>> compiled expressions in Python?)
>>
>
> Yes, I think that if there is a gap in the sense that we don't have a
> demo to illustrate the use of a particular mainstream feature, then we
> should formulate a demo, preferably something interesting, to
> demonstrate the feature. For more complicated features, we might want
> the demo to focus strongly on a particular feature.
>
> Garth
>

It could be an idea to order the demos like they've done in deal.II. Then
the second
demo does only need to document how it is different from the first. Of
course, the
name of the demos are more descriptive so they should not be taken away,
but there
could be a suggested path through the demos. The path could be then one in
the tutorial of HPL or some other document.

And I think it is important that we get an online reference, automatically
generated for
both C++ and Python for both stable and developement versions.

Kent