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

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.

What would probably change my mind would be a two-way (or multi-way) 
tool:  it takes input in Roxygen comments or Rd files (or something 
else), and produces another format.  Then I'd probably choose to write 
the first pass in Roxygen, and convert to Rd for editing.  Other people 
might go in the opposite direction.  Or someone might write a fancy 
WYSIWYG editor for people who like that style of editing.

A couple of years ago I was hoping someone would figure out a way to 
create help page input in R Markdown, but I think that's tricky because 
of the lack of semantic markup there.  There *was* a project last year 
to work on other input methods; I dropped out before it got very far, 
and I don't know its current status.
> 
> 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.
> 
> What Duncan may be observing is a general tendency of roxygen2 users to
> write overly concise documentation. However, I believe this to be caused by
> an omitted variable - likely the tendency of roxygen2 users to want outputs
> quickly. I can't see anything in roxygen2 that might suggest a causal
link
> but I'd be interested in hearing specific examples.
I don't know about that.  *Everyone* wants output quickly.

Duncan Murdoch

> FWIW, I've also heard the same documentation criticism leveled at R in
> general (mostly from Stata and MATLAB users).
> 
> Kenny
> 
> On Wed, Jan 31, 2018, 10:12 AM Dirk Eddelbuettel <edd at debian.org>
wrote:
> 
>>
>> Mehmet,
>>
>> That is a loaded topic, not unlikely other topics preoccupying us these
>> days.
>>
>> There is package.skeleton() in base R as you already mentioned. It
drove me
>> bonkers that it creates packages which then fail R CMD check, so I
wrote a
>> wrapper package (pkgKitten) with another helper function (kitten())
which
>> calls the base R helper and then cleans up it---but otherwise remains
>> faithful to it.
>>
>> These days pkgKitten defaults to creating per-package top-level help
page
>> that just references content from DESCRIPTION via a set of newer Rd
macros
>> as
>> I find that helps keeping them aligned. The most recent example of mine
is
>>    https://github.com/eddelbuettel/prrd/blob/master/man/prrd-package.Rd
>> I use either this function or the RStudio template helper all the time.
>>
>> And similarly, other people written similar helpers. You may get other
>> pointers.
>>
>> And every couple of months someone writes a new tutorial about how to
>> write a
>> first package. Then social media goes gaga and we get half a dozen blog
>> posts
>> where someone celebrates finding said tutorial, reading it and
following
>> through with a new package.
>>
>> And many of us taught workshops on creating packages. There is a lot of
>> material out here, though lots of this material seems to be entirely
>> ignorant
>> of what came before it.
>>
>> And there has been lots, including Fritz's tutorial from a decade
ago:
>>
>>      https://epub.ub.uni-muenchen.de/6175/  as well as on CRAN as
>>      https://cran.r-project.org/doc/contrib/Leisch-CreatingPackages.pdf
>>
>> So I'd recommend you just experiment and set up your own helpers.
After all
>> the rule still holds: Anything you do more than three times should be a
>> function, and every function should be in a package. So customize
_your_
>> function to create your package.
>>
>> Dirk
>>
>> --
>> http://dirk.eddelbuettel.com | @eddelbuettel | edd at debian.org
>>
>> ______________________________________________
>> R-devel at r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>
> 
> 	[[alternative HTML version deleted]]
> 
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

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

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

Hadley

-- 
http://hadley.nz

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