fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

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

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

> 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

Attachment: signature.asc
Description: Digital signature