fenics team mailing list archive

["Anna Blechingberg" <anna.blechingberg@xxxxxxxxxxxxx>]

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

I agree with the previous commentaries. One idea could also be to have
references in the demos to the tutorial or the documentation. For example
"see page 40 in the Tutorial for an explanation and other variants of
coding this." Or "compare with the ?? demo that solves this problem with
the ?? method" or "this code is explaned in the ?? demo".

Anna



> _______________________________________________
> Mailing list: https://launchpad.net/~fenics
> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~fenics
> More help   : https://help.launchpad.net/ListHelp
>