On Thu, Mar 18, 2010 at 02:47:48PM +0100, Andre Massing wrote: > 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 )
There's no question we need much more detailed documentation, the question is just where to put it. Either as part of the code or separately. Perhaps it is just a matter of figuring out how to write the verbose comments in a way that looks good. -- Anders > > > > > 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. > > >> > > > > > > _______________________________________________ > > > Mailing list: https://launchpad.net/~fenics > > > Post to : [email protected] > > > Unsubscribe : https://launchpad.net/~fenics > > > More help : https://help.launchpad.net/ListHelp > > > > _______________________________________________ > > Mailing list: https://launchpad.net/~fenics > > Post to : [email protected] > > Unsubscribe : https://launchpad.net/~fenics > > More help : https://help.launchpad.net/ListHelp > > _______________________________________________ > Mailing list: https://launchpad.net/~fenics > Post to : [email protected] > Unsubscribe : https://launchpad.net/~fenics > More help : https://help.launchpad.net/ListHelp
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
