On 02/07/2013 05:00 AM, r-help-requ...@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.
Terry Therneau
______________________________________________
R-help@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
