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
signature.asc
Description: Digital signature
_______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : [email protected] Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp
