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

Kenny Bell kmbell56 at gmail.com
Tue Jan 30 22:30:58 CET 2018

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.

Writing my first piece of R documentation was made much easier by using
roxygen2, and it shallowed the learning curve substantially.

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.

FWIW, I've also heard the same documentation criticism leveled at R in
general (mostly from Stata and MATLAB users).


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

More information about the R-devel mailing list