fenics team mailing list archive

[Andre Massing <massing@xxxxxxxxx>]

On Thursday 18. March 2010 06.17.35 Garth N. Wells wrote:
> 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.

I must admit that I strongly prefer more detailed comments over too little 
comments, mainly with the user in mind.  Firstly for the user it is easier to 
jump over a comment in documentation when he/she understands what happens then 
to think about and find out what a certain function might do if there is too 
little or no description. Secondly as a developer we often tend to be too much 
into the topic. We think that meaningful names of functions and arguments 
should be almost self-explanatory, but for the average user it is often not 
the case.  He/she does not want to study source code but only want to *use* 
the lib and interface, so I think few additional lines can clarify a lot. For 
example, QT's success is amongst other things also largely based on its well 
documented library. Almost everybody appreciates the detailed documentation.
If comments hide the source code I  would rather think about another way of 
adding descriptions then just reducing it. And at least for me with a good 
editor with syntax highlighting and maybe text folding and a ctags-plugin it 
is no problem to immediately find the line of code I am looking for (yepp it is 
gvim ;-P )


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

I think that sounds pretty good to have in a sense gradually varying demos and 
it seems to me that DOLFIN has already a pretty cool demo base for accomplish 
this. So what about adding some kind of "big picture" demo, solving some 
rather sophisticated problems, e.g fluid-structure-interaction, which involve 
quite a few features of DOLFIN? The documentation of these ones could point to 
corresponding specialized demos dedicated for single feature classes. Such 
kind of examples might also added to the tutorial as some good "Now we put 
everything together example" similiar as Hans-Petter Langtangen already do  
(e.g. " A general d-Dimensional Multi-Material Test Problem", section 7). I 
really like that style of gradually increasing complexity of Hans Petters 
tutorial and I aggree with Anne that it would be a good idea to map tutorial 
and demos closely. 

Andre

> 
> > Johan
> > 
> >> As you are all aware, FEniCS is lacking good documentation. The
> >> situation will improve when the FEniCS book comes out, but it will
> >> not replace a comprehensive user manual.
> >> 
> >> A very good solution to this problem has just presented itself. I
> >> have some grant money that could go towards creating good
> >> documentation and I have also found an ideal candidate in Kristian
> >> Oelgaard. He should really be finishing up his thesis but has kindly
> >> accepted to work part-time on the manual. :-)
> >> 
> >> So, let's hear some opinions on what kind of documentation users need.
> >> 
> >> Kristian, Garth, Hans Petter and I have had some initial discussions
> >> and here are some thoughts so far. Let's get the discussion going.
> >> 
> >> 1. The new documentation will consist of two parts, one called
> >> "FEniCS User Manual" and one called "FEniCS Tutorial". The first one
> >> will be a comprehensive manual and the second will be a tutorial based
> >> on Hans Petter's tutorial chapter for the FEniCS book.
> >> 
> >> 2. Both the user manual and tutorial will come in two different
> >> flavors, one C++ and Python. With some clever use of LaTex \input, it
> >> should be possible to handle with not too much extra work.
> >> 
> >> 3. The user manual will replace the current user manuals for DOLFIN,
> >> FFC, UFL and UFC. What we have now in those manuals can be used as
> >> input.
> >> 
> >> 4. The manual will focus on the user experience and therefore
> >> concentrate on the DOLFIN interface. Specific details for FFC, UFL and
> >> UFC will be made appendices in the new manual.
> >> 
> >> 5. The manual will be available both as a PDF file and online HTML.
> >> Hans Petter has pointed out a new tool called doconce that might be
> >> useful for generating PDF, HTML and docstrings from a common source.
> >> This is worth investigating as docstrings are also important and it's
> >> extra work to maintain both docstrings and manual.
> >> 
> >> 6. We need well-documented demos. It's currently unclear what the
> >> relation is between the manual, documented demos, current demos in
> >> DOLFIN and the examples in Hans Petter's tutorial so we need to work
> >> out a model for this.
> >> 
> >> --
> >> Anders
> >> 
> >> PS: The project page is here, so make sure to subscribe if you want to
> >> 
> >> follow the development of the documentation:
> >>    https://launchpad.net/fenics-doc
> >> 
> >> There is (yet) no special mailing list for the documentation but
> >> perhaps it will be enough to use this list.
> > 
> > _______________________________________________
> > Mailing list: https://launchpad.net/~fenics
> > Post to     : fenics@xxxxxxxxxxxxxxxxxxx
> > Unsubscribe : https://launchpad.net/~fenics
> > More help   : https://help.launchpad.net/ListHelp
> 
> _______________________________________________
> Mailing list: https://launchpad.net/~fenics
> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~fenics
> More help   : https://help.launchpad.net/ListHelp