On 10/8/11 7:44 AM, Sébastien Brisard wrote: > Hi, > I've spent quite a lot of time going through Pr. Saunders' FORTRAN > implementation of this algorithm, and the Java port is almost ready. > This algorithm is quite difficult to read, because some quantities > required at iteration k can be computed only in iteration (k+1). So > one must be careful in managing the loops, and especially moving > around some pieces of code. I feel that for maintenance purposes in > the future (for example, when we will be ready to introduce custom > stopping criteria), it would be useful to have detailed implementation > notes, where the correspondance between Java variables and the > mathematical variables of the original paper (including the index of > the iteration!) would be clearly stated. > > I've taken some notes for myself, it would be useful if those notes > were actually shipped with the code (or would it?). Considering the > recent posts on the sine cardinal, Javadoc are *definitely* not the > place where I should put these notes.
Things that impact the contract of the API - i.e., what is being computed, what algorithm is being used, exceptions, boundary cases, etc., should all be covered in the javadoc. You can link to external documents to describe algorithms, but the javadoc needs to fully document the API. How the implementation works is a different matter. See below. > Where should these go > - separate document (LaTeX), which would go in a linear/doc-files > subdirectory in order to be copied with the javadoc (which could point > at that document) > - html page in the website (User Guide? But this is really intended > for developers) > - any other option? > > In any case, the notes would benefit from a little bit of mathematical > formatting. My preferred option would be LaTeX, but I can live with an > HTML page with embedded MathML (provided the Commons-Math site > resulting from mvn site:site can support MathML -- anyone ever > tried?). > > Do you think that these notes should really be attached to the CM > library? If yes, any suggestion as to where and how? This is a good question and one that applies to lots of other things that are not too well documented now. I would be fine with adding a section to the web site on implementation notes, using pdf as publication format, TeX as source format, assuming there is no maven plugin to create pdfs from TeX source on the fly, storing both in svn, and including the pdfs with the user guide - only site shipped with the binary distro. An alternative would be to publish the notes externally and link to them. Its a lot of work, but there are probably quite a few interesting (free access!) articles that could be written based on things already in [math]. I would encourage you, though, to add as much inline, class and javadoc documentation as possible, since that is what developers looking at the source will see immediately. Phil > > Thanks! > Sébastien > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
