First R Package --- Advice?

I have heard of people using noweb to do this, but I can't point to any
examples.  I'd actually recommend against it.  Good documentation files
don't
make good source files.

the compiler package in base R is, apparently, developed using noweb
https://svn.r-project.org/R/trunk/src/library/compiler/noweb, which provide
excellent documentation of the code for other developers and is not quite
what Ivo was suggesting.

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 (as evidence see the 400
page latex package manuals that don't help you at all)