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

[Georgi Boshnakov]

It is indeed a matter of what the developer is comfortable with and the one-stop solution provided by devtools is difficult to beat. 
This may also vary across projects. I use EMACS/ESS with and without roxygen2. In some cases EMACS/ESS+Org mode provides stunning benefits.

Updating "usage" statements in Rd files was mentioned several times. 
Rdpack::reprompt() does this and more for functions, methods and classes. 


Georgi Boshnakov

------------------------------
Date: Wed, 31 Jan 2018 07:53:18 -0800
From: Michael Lawrence <lawrence.michael at gene.com>
To: Duncan Murdoch <murdoch.duncan at gmail.com>
Cc: "Brian G. Peterson" <brian at braverock.com>, "Suzen, Mehmet"
	<mehmet.suzen at gmail.com>, R-devel <r-devel at r-project.org>
Subject: Re: [Rd] Best practices in developing package: From a single
	file
Message-ID:
	<CAOQ5NyequDcsBczAqOg6XqDeUNx2hXg+4ggHc0Ews0NxgszHSA at mail.gmail.com>
Content-Type: text/plain; charset="UTF-8"

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
>