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

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

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

I think you want to see the approach to generating a skeleton from a single .R
file presented in:

	Simple and sustainable R packaging using inlinedocs
http://inlinedocs.r-forge.r-project.org/

I have not used it in some time but found it invaluable when I did.

I would be VERY INTERESTED to hear how others feel it has held up.

Joining conversation late,

~malcolm_cook at stowers.org

 > >
 > > 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 mailing list
 > https://stat.ethz.ch/mailman/listinfo/r-devel

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

On 30 January 2018 at 21:31, Cook, Malcolm <MEC at stowers.org>
wrote:
>
> I think you want to see the approach to generating a skeleton from a single
.R file presented in:
>
>         Simple and sustainable R packaging using inlinedocs
http://inlinedocs.r-forge.r-project.org/
>
> I have not used it in some time but found it invaluable when I did.
For the record, the package has a JSS article as well:

https://www.jstatsoft.org/article/view/v054i06


Best,
-m

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.

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

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.

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.

Kind regards
Joris



On Tue, Jan 30, 2018 at 8:53 PM, Duncan Murdoch <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 mailing list
> 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

	[[alternative HTML version deleted]]

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

On 31/01/2018 6:33 AM, Joris Meys wrote:
> 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.
After this invitation I sent some private comments to Joris.  I would 
say his package does a pretty good job of documentation; it isn't the 
kind of Roxygen-using package that I was complaining about.  So I will 
say I have received an example of a Roxygen-using package that
has good help pages.

Duncan Murdoch

I pretty much agree. I tried using roxygen when it was first released but
couldn't stand putting documentation in comments, especially for complex,
S4-based software. Rd is easy to read and write and lets me focus on the
task of writing documentation (focus is the hardest part of any task for
me). Probably the best feature of roxygen is that it automatically
generates \usage{}, which is otherwise completely redundant with the code.

I think the preceeding systems like doxygen, javadoc, gtk-doc, qtdoc, etc,
found a nice compromise through templating, where the bulk of the details
are written into the template, and just the essentials (usage, arguments,
return value) were embedded in the source file. I think this is even more
important for R, since we're often describing complex algorithms, while
most C/C++/Java software is oriented complex classes containing many
relatively simple methods.

Michael


On Tue, Jan 30, 2018 at 11:53 AM, Duncan Murdoch <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 mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>
	[[alternative HTML version deleted]]