R devel - Feb 2018 - Fwd: Re: Best practices in developing package:

> 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.

> On 1 f?vr. 2018, at 06:51, Therneau, Terry M., Ph.D. <therneau at
mayo.edu> wrote:
> 
> 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.
Good point. It suggests editors need folding support for roxygen sections.

Lionel

Folding is a simple solution, but there are intrinsic problems, like the
need to embed the documentation in comments. If the user already has to
expand a fold to edit the docs, the IDE could instead just provide a link
or shortcut that jumps to a separate documentation file, written in
whatever language, Rd, markdown, docbook. For example, I could imagine
RStudio showing the rendered documentation in a side pane when the cursor
is on the function name/signature, and the user could somehow switch modes
to edit it. But there would be no need to mix two different languages in
the same file, and thus no ugly escaping, and no documentation obscuring
the code, or vice versa.

On Thu, Feb 1, 2018 at 7:20 AM, Lionel Henry <lionel at rstudio.com>
wrote:
>
> > On 1 f?vr. 2018, at 06:51, Therneau, Terry M., Ph.D. <therneau at
mayo.edu>
> wrote:
> >
> > 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.
>
> Good point. It suggests editors need folding support for roxygen sections.
>
> Lionel
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>
	[[alternative HTML version deleted]]