fenics team mailing list archive

[Andre Massing <massing@xxxxxxxxx>]

On Saturday 20. March 2010 10.15.52 Anders Logg wrote:
> On Thu, Mar 18, 2010 at 09:40:00AM +0000, Chris Richardson wrote:
> > As a user who has come to FEniCS in the last month or so, I have
> > some direct experience of
> > the existing documentation. I just wanted to make a few points,
> > which do represent a personal point of view, but are probably also
> > representative of a certain type of user.
> > 
> > Paper-style documentation in pdf or book form is not very useful.
> > Whilst I would read something like that if studying maths or
> > physics, HTML is much more useful for a computing language. Examples
> > can be downloaded, and it is much more easily searchable.
> > 
> > The demos are great, and the best thing you've got at the moment. I
> > find myself using "grep" on them to find the specific feature which
> > I am interested in. I agree that they shouldn't be too heavily
> > commented.
> > 
> > The doxygen generated documentation is fine, but it is a bit
> > overwhelming, and it has no examples in it.
> > 
> > My preferred documentation model would be something like
> > perldoc.perl.org or php.net which have
> > well-written pages on each function etc. with sections on
> > parameters, return values, links to related functions, and examples.
> > If you have something like this, plus the demos, that's all you
> > need.
> 
> The perldoc looks nice, but it illustrates the problem of
> autogenerating documentation from the code. For example, look at the
> documentation for caller:
> 
>   http://perldoc.perl.org/functions/caller.html
> 
> This is the level of verbosity we need and it would clutter up the
> header files. Here's an example from IntersectionOperator.h that I
> personally think looks ugly (sorry Andre...):

No way to talk it away, it looks ugly, no question.

> 
>     ///Compute all id of all cells which are intersects by a \em entity.
>     ///\param[out] ids_result The ids of the intersected entities are
>     saved in a vector.
>     ///This allows is more efficent than using a set and allows a map
>     between
>     //the (external) cell and the intersected cell of the mesh. If you
>     //are only interested in intersection with a list of cells without
>     caring about which
>     //cell what intersected by which one, use
>     // void IntersectionOperator::all_intersected_entities(const
>     std::vector<Cell> &, uint_set &) const;
>     /////@internal
>     ///@todo This function has to improved: 1) it requires the object
>     the
>     //mesh is to be cut with to be another mesh entitiy instead of
>     being just a
>     //kind of geometric object. 2) Requires a runtime switch 3) would
>     require a
>     //implementation for each geometric  primitive if they have no
>     common base
>     //class.
>     void all_intersected_entities(const MeshEntity & entity,
> std::vector<uint> & ids_result) const;
> 
> Perhaps it is just a question of formatting and it could be made to
> look better.

Even better formatting would probably not prevent from having a (too) high 
comment to code line ratio :(. I agree that the code looks overly cluttered, I 
would also be happy to have a solution at hand which allows both for verbose 
documentation (and maybe even internal notes, which the the comment example 
above contains) and keeping the code clean. On the other hand the main 
advantage of source embedded documentation is that you can document the code 
while you are writing it, meaning it is easily embedded into the 
implementation workflow. It would be nice to have a kind out of source 
documentation tool, which does not add too much extra work to write 
documentation.

> 
> > Another model would be to use something like "dokuwiki" which would
> > allow collaboration on generating  searchable, crosslinked
> > documentation with embedded examples.
> > 
> > Chris Richardson
> > 
> > P.S. I'm happy to help with the documentation effort in any way,
> > e.g. proof-reading, road-testing, etc. once it
> > is decided.
> 
> Great.
> 
> --
> Anders