[Rd] Fwd: Re: Best practices in developing package:

[Therneau, Terry M., Ph.D.]

> I'm not going to force anyone to use roxygen2. But I personally find it
> easier to have the function right below the documentation, so that any
> change to the function can immediately be documented as well. You prefer to
> do this by keeping that strictly separated, which is absolutely fine. It's
> just not my prefered workflow. Different animal, different habits I guess.
> 

Lest Duncan be left standing all alone let me say that I am another who really dislikes
the roxygen style.  Joris' comment above is a key one though; the goal is good
documentation and any tool to that end is just a tool.  One driver for my preferences is
that I don't like editing large files, e.g., in the survival package every function is a
separate file.  A second is that I care a lot about documentation so my help files are
fairly long, so much so that the advantage of having the documentation of an argument
"close" to the declaration of said argument is lost.

The closeness argument works best when the documentation for each argument is a terse half
sentence, and in that sense roxygen encourages minimalist documentation.  But the real
issue with poor documentation is the orneriness of the writers: good documentation is hard
work and most don't bother.  For most R packages lines of code > lines of documentation >
lines of test suite, usually by a factor of 10 at each stage.  One of my goals for the
survival package has been to make them more equal with 'lines of documentation' the
largest.  I'm getting closer: currently 17395 lines in the R subdirectory, 8042 + 8841 in
man + vignettes, and 6000 in test.

A challenge for someone who is better at document analysis than me: what is the distribution
of the ratios above, across CRAN packages?  Is my 10:1 impression optimistic?

  Terry T.