[R] First R package, advice
therneau at mayo.edu
Fri Feb 8 19:46:43 CET 2013
On 02/07/2013 05:00 AM, r-help-request at r-project.org wrote:
> I'd argue that there's an important distinction between documenting a
> function (how to use it) vs. documenting an algorithm (how it works).
> I think noweb can work well for describing how something works, but
> it's not so good for describing how to use it
I'm a big fan of noweb for the source code, take a look a the coxme package for extensive
use of this. That contains the most complex mathematics of any code I have written, and
it is a big help to have real equations and discussion mixed in with the code. The sparse
matrix algorithms aren't very transparent either so it is a plus on that front too. A big
help to me whenever I look back at something.
That given, I agree with the above that documentation of the algorithm and
documentation of useage are disjoint tasks. The pdf file from my noweb source is of
critical importance to someone changing the code, and of essentially no use to anyone
else. Use vignettes for the latter.
More information about the R-help