[Rd] Best practices in developing package: From a single file

[Duncan Murdoch]

On 30/01/2018 11:39 PM, Hadley Wickham wrote:
> On Tue, Jan 30, 2018 at 4:55 PM, Duncan Murdoch
> <murdoch.duncan at gmail.com> wrote:
>> On 30/01/2018 4:30 PM, Kenny Bell wrote:
>>>
>>> In response to Duncan regarding the use of roxygen2 from the point of view
>>> of a current user, I believe the issue he brings up is one of correlation
>>> rather than causation.
>>
>>
>> Could be.  However, I think editing comments in a .R file is a bit harder
>> than editing text in a .Rd file, so I think the format discourages editing.
>> I think it does make it easier to pass R CMD check the first time, but I
>> don't think you should be satisfied with that.
> 
> One counter-point: I find it much easier to remember to update the
> documentation when you update the code, if the code and the
> documentation are very close together. I think mingling code and
> documentation in the same file does add a subtle pressure to write
> shorter docs, but I'm not entirely sure that's a bad thing - for long
> form writing, vignettes are a much better solution anyway (since you
> often want to mingle code and explanation).

I agree about your first point to some extent, but it works best when 
the documentation is short.  Once you get a long help page, you still 
have the long distance.  Some functions need long help pages because 
they do a lot.

RStudio provides pretty good support for both forms of documentation. 
If I've just modified a function, I can type the name of the function in 
the "Go to file/function" box at the top, and go directly to the right 
.Rd file.  That reduces the "distance".  I imagine ESS and other editors 
have (or could have) something similar.

Regarding vignettes versus help pages:  I think they have different 
purposes.  You want the technical documentation in the help page to be 
really complete, to explain what each parameter does, what the value is, 
with simple examples.  I won't try to embarrass anyone with specific 
examples (unless someone volunteers ;-), but I would say the general 
trend in Roxygen-using packages is to be quite incomplete, with one-line 
parameter descriptions being all you get.  Sometimes this is sufficient, 
but often it isn't.  The goal appears to be to pass checks, not to write 
good documentation.  Some wild speculation:  maybe the proximity to the 
source makes authors think the source is visible to the user looking for 
help.

Vignettes get to leave out rarely used parameters, but get to show how 
things are used in longer examples, combining multiple functions.  I've 
tried to write the rgl documentation this way, with links from the 
vignette to the help pages.

I haven't added links from the help page to the location in the vignette 
where the function is put in context, but that's probably possible 
(provided HTML help is used, and the vignette is in HTML).

> Personally, I don't find writing in comments any harder than writing
> in .Rd files, especially now that you can write in markdown and have
> it automatically translated to Rd formatting commands.  

I didn't know about the possibility of Markdown.  That's a good thing. 
You didn't say what editor you use, but RStudio is a good guess, and it 
also makes it easier to write in comments.

And on the
> negative side of Rd, I find it frustrating to have to copy and paste
> the function definition to the usage section every time I modify an
> argument. It just feels like unnecessary busywork that the computer
> should be able to do for me (although I do understand why it is not
> possible).

The computer (via R CMD check) does tell you what is missing.  I'd guess 
that the transfer could be done automatically, but it would be in a very 
editor-specific way, e.g. an RStudio add-in, or Emacs macro, or 
whatever.  Someone should write it :-).

> 
>>> Writing my first piece of R documentation was made much easier by using
>>> roxygen2, and it shallowed the learning curve substantially.
>>
>> I'm not completely up to date on Roxygen2 these days:  can you do some pages
>> in Rd, others in Roxygen?  That's not quite as good as being able to switch
>> back and forth, but it would allow you to start in Roxygen, then gradually
>> move to Rd when editing there was easier.
> 
> Yes, that's possible, and to protect you in mixed environment,
> roxygen2 will never overwrite a file that it did not itself create.

Good!  Perhaps I should give it another look.

Duncan