First R package, advice

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