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

Duncan Murdoch murdoch.duncan at gmail.com
Wed Jan 31 13:10:07 CET 2018

On 31/01/2018 6:33 AM, Joris Meys wrote:
> Dear Duncan,
> With all respect, but I strongly disagree on your stance regarding 
> roxygen2 for multiple reasons:
> 1. It is in my humble opinion not correct to evaluate a tool based on 
> the abuse of some users. It's not because people write packages with bad 
> documentation, that roxygen2 is to blame. I use roxygen2, and I care a 
> great deal about documentation. So I actually took a bit offense there.

Sorry about that.  I did say I wanted to be proven wrong.

> 2. Writing .Rd files directly means that you have to write out the usage 
> yourself, know the different tags needed for documenting different types 
> of generics and methods, and so forth. 

Not at all --- that's what the prompt() function does.

> It means a lot more iterations to 
> get every tag right so that R CMD check does not complain any more. It 
> requires a more detailed knowledge of the entire Rd tag system compared 
> to letting roxygen2 do the standard work for you. So one could argue 
> that the extra knowledge required would actually hinder starting 
> developers to write good documentation as opposed to help them.

New users (and old users) should use prompt() to set up the basic help page.

There are situations where prompt() doesn't help, namely edits to 
existing pages:

  - adding a second function.
  - adding new parameters.

I think the infrastructure is there to allow functions to be written to
do these things, but as far as I know nobody has done it.

> 3. given your criticism, I'd like your opinion on where I can improve 
> the documentation of https://github.com/CenterForStatistics-UGent/pim. 
> I'm currently busy updating the help files for a next release on CRAN, 
> so your input is more than welcome.

Sure, I'll take a look.

> 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.
> On a sidenote: I had a lot of complaints about earlier iterations of 
> roxygen2 and the many changes to tags and their meanings, but the 
> roxygen2 package matured in the meantime and has been a stable and 
> reliable tool for me the past years.

I formed my opinion several years ago, so perhaps I should take another 
look.  One problem is lock-in:  once you write an Rd file, you can't (as 
far as I know) easily import it as Roxygen markup.  So I'd have to start 
a new package to get experience with Roxygen.  Maybe it should be the 
package that adds the Rd tools mentioned above :-).

Duncan Murdoch

> Kind regards
> Joris
> On Tue, Jan 30, 2018 at 8:53 PM, Duncan Murdoch 
> <murdoch.duncan at gmail.com <mailto:murdoch.duncan at gmail.com>> wrote:
>     On 30/01/2018 11:29 AM, Brian G. Peterson wrote:
>         On Tue, 2018-01-30 at 17:00 +0100, Suzen, Mehmet wrote:
>             Dear R developers,
>             I am wondering what are the best practices for developing an R
>             package. I am aware of Hadley Wickham's best practice
>             documentation/book (http://r-pkgs.had.co.nz/).  I recall a
>             couple of
>             years ago there were some tools for generating a package out
>             of a
>             single file, such as using package.skeleton, but no
>             auto-generated
>             documentation. Do you know a way to generate documentation and a
>             package out of single R source file, or from an environment?
>         Mehmet,
>         This list is for development of the R language itself and closely
>         related tools.  There is a separate list, R-pkg-devel, for
>         development
>         of packages.
>         Since you're here, I'll try to answer your question.
>         package.skeleton can create a package from all the R functions in a
>         specified environment.  So if you load all the functions that
>         you want
>         in your new package into your R environment, then call
>         package.skeleton, you'll have a starting point.
>         At that point, I would probably recommend moving to RStudio, and
>         using
>         RStudio to generate markdown comments for roxygen for all your newly
>         created function files.  Then you could finish off the
>         documentation by
>         writing it in these roxygen skeletons or copying and pasting from
>         comments in your original code files.
>     I'd agree about moving to RStudio, but I think Roxygen is the wrong
>     approach for documentation.  package.skeleton() will have done the
>     boring mechanical part of setting up your .Rd files; all you have to
>     do is edit some content into them.  (Use prompt() to add a new file
>     if you add a new function later, don't run package.skeleton() again.)
>     This isn't the fashionable point of view, but I think it is easier
>     to get good documentation that way than using Roxygen.  (It's easier
>     to get bad documentation using Roxygen, but who wants that?)
>     The reason I think this is that good documentation requires work and
>     thought.  You need to think about the markup that will get your
>     point across, you need to think about putting together good
>     examples, etc.
>     This is *harder* in Roxygen than if you are writing Rd files,
>     because Roxygen is a thin front end to produce Rd files from
>     comments in your .R files.  To get good stuff in the help page, you
>     need just as much work as in writing the .Rd file directly, but then
>     you need to add another layer on top to put in in a comment.  Most
>     people don't bother.
>     I don't know any packages with what I'd consider to be good
>     documentation that use Roxygen.  It's just too easy to write minimal
>     documentation that passes checks, so Roxygen users don't keep
>     refining it.
>     (There are plenty of examples of packages that write bad
>     documentation directly to .Rd as well.  I just don't know of
>     examples of packages with good documentation that use Roxygen.)
>     Based on my criticism last week of git and Github, I expect to be
>     called a grumpy old man for holding this point of view.  I'd
>     actually like to be proven wrong.  So to anyone who disagrees with
>     me:  rather than just calling me names, how about some examples of
>     Roxygen-using packages that have good help pages with good
>     explanations, and good examples in them?
>     Back to Mehmet's question:  I think Hadley's book is pretty good,
>     and I'd recommend most of it, just not the Roxygen part.
>     Duncan Murdoch
>     ______________________________________________
>     R-devel at r-project.org <mailto:R-devel at r-project.org> mailing list
>     https://stat.ethz.ch/mailman/listinfo/r-devel
>     <https://stat.ethz.ch/mailman/listinfo/r-devel>
> -- 
> 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

More information about the R-devel mailing list