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. ______________________________________________ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
