R devel - Feb 2018 - Best practices in developing package: From a single file

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

On 31/01/2018 6:59 AM, Duncan Murdoch wrote:
> On 30/01/2018 11:39 PM, Hadley Wickham wrote:
  [ lots deleted ]
>> 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.
I've taken a look at the Markdown support, and I think that is 
fantastic.  I'd rather it wasn't inline in the .R file (does it have to 
be?), but I'd say it tips the balance, and I'll certainly experiment 
with using that for new projects.

The only negative I see besides forcing inline docs is pretty minor:  I 
can see that supporting Rd markup within the Markdown text will on rare 
occasions cause lots of confusion (because users won't know why their 
backslashes are doing funny things).  I'd suggest that (at least 
optionally) you should escape anything that looks like Rd markup, so a 
user can put text like \item into the middle of a paragraph and not have 
the Rd parser see it.

Duncan Murdoch

On Thu, Feb 1, 2018 at 1:29 PM, Duncan Murdoch <murdoch.duncan at
gmail.com>
wrote:
> On 31/01/2018 6:59 AM, Duncan Murdoch wrote:
>
>> On 30/01/2018 11:39 PM, Hadley Wickham wrote:
>>
>  [ lots deleted ]
>
>> 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.
>>
>
> I've taken a look at the Markdown support, and I think that is
fantastic.
> I'd rather it wasn't inline in the .R file (does it have to be?),
but I'd
> say it tips the balance, and I'll certainly experiment with using that
for
> new projects.
>
You don't have to put the Rmarkdown in the .R file of the function, there
are ways to keep them in separate files. But keeping them in the same file
does make it easier for Rmarkdown to eg generate the correct usage section
and use the correct Rd makeup etc. At least that's my understanding of it.
Hadley will hopefully correct me if I'm wrong.  I haven't checked all
the
options and possibilities yet in the latest iterations of the package.

Cheers
Joris

-- 
Joris Meys
Statistical consultant

Department of Data Analysis and Mathematical Modelling
Ghent University
Coupure Links 653, B-9000 Gent (Belgium)
<https://maps.google.com/?q=Coupure+links+653,%C2%A0B-9000+Gent,%C2%A0Belgium&entry=gmail&source=g>

-----------
Biowiskundedagen 2017-2018
http://www.biowiskundedagen.ugent.be/

-------------------------------
Disclaimer : http://helpdesk.ugent.be/e-maildisclaimer.php

	[[alternative HTML version deleted]]

On Thu, Feb 1, 2018 at 4:29 AM, Duncan Murdoch <murdoch.duncan at
gmail.com> wrote:
> On 31/01/2018 6:59 AM, Duncan Murdoch wrote:
>>
>> On 30/01/2018 11:39 PM, Hadley Wickham wrote:
>
>  [ lots deleted ]
>>>
>>> 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.
>
>
> I've taken a look at the Markdown support, and I think that is
fantastic.
> I'd rather it wasn't inline in the .R file (does it have to be?),
but I'd
> say it tips the balance, and I'll certainly experiment with using that
for
> new projects.
Please do let me know how it goes - often a fresh set of eyes reveals
problems that an experienced user is blind to.
> The only negative I see besides forcing inline docs is pretty minor:  I can
> see that supporting Rd markup within the Markdown text will on rare
> occasions cause lots of confusion (because users won't know why their
> backslashes are doing funny things).  I'd suggest that (at least
optionally)
> you should escape anything that looks like Rd markup, so a user can put
text
> like \item into the middle of a paragraph and not have the Rd parser see
it.
Yes, that would certainly be nice. It's a little challenging because
we're using the commonmark parser, but it should be possible somehow.

Hadley

-- 
http://hadley.nz