[R] First R Package --- Advice?

[Duncan Murdoch]

On 06/02/2013 9:44 AM, Martin Morgan wrote:
> On 02/06/2013 03:31 AM, Duncan Murdoch wrote:
> > On 13-02-05 7:43 PM, ivo welch wrote:
> >> Dear R experts---
> >>
> >> after many years, I am planning to give in and write my first R
> >> package.  I want to combine my collection of collected useful utility
> >> routines.
> >>
> >> as my guide, I am planning to use Friedrich Leisch's "Creating R
> >> Packages: A Tutorial" from Sep 2009.  Is there a newer or better
> >> tutorial?  this one is 4 years old.
> >>
> >> I also plan on one change---given that the package.skeleton() function
> >> writes all the individual man[ual] functions, I am thinking it would
> >> be a good idea to put the doc and the R code together in the same
> >> file, one for each function.  Interestingly enough, the code is by
> >> default in the \examples{} section, so I am thinking of writing a perl
> >> program that takes every .Rd file and writes the function into the R/
> >> directory, overwriting anything else that is already there.  this way,
> >> I maintain only one file for each function, and the docs and code are
> >> together.  sort of like knuth's literate programming and the
> >> numerical-recipees approach to keeping each function in its own file
> >> with equal name.
> >
> > I have heard of people using noweb to do this, but I can't point to any
> > examples.  I'd actually recommend against it.  Good documentation files don't
> > make good source files.
>
> the compiler package in base R is, apparently, developed using noweb
> https://svn.r-project.org/R/trunk/src/library/compiler/noweb, which provide
> excellent documentation of the code for other developers and is not quite what
> Ivo was suggesting.
>
> >
> > If you really want close connections between your source and the user
> > documentation, I think that's the job of your IDE.  (I don't find this to be a
> > problem, so I don't use an IDE that attempts this, but I believe they exist:
> > I'd look at ESS, RStudio, RKWard if I was in the market for that.)
> >
> > Other people have recommended Roxygen, but honestly I haven't seen a package
> > documented with Roxygen where the documentation was adequate.
> > It looks as though it's great to get initial documentation created, but does not
> > appear to encourage followup.
> >
> >>
> >> I believe my "try-out and debug cycle" will then be
> >>
> >>     $ cd iaw  ## the package name and top directory is iaw
> >>     $ perl weaveall.pl   ## extract all man/*.Rd files code examples
> >> and place them in R/
> >>     $ R CMD INSTALL iaw
> >>     $ R CMD check iaw
> >
> > I wouldn't put the last step in this cycle.  Have a separate check cycle, which
> > includes a build step, and checks the built tarball.
> >
> >
> >>
> >> good idea?  bad idea?  common?  uncommon?
> >>
> >> I do not understand the namespace mechanism yet.  I understand the
> >> NAMESPACE file, and I think this lists the routines that become
> >> visible when a later program of mine contains 'library(iaw)'.  I think
> >> I want to explicitly declare what packages are actually imported.
> >> ?importIntoEnv tells me that it is not intended to be used.  how can
> >> another program declare exactly what functions it wants to import?
> >> (frankly, I would love to turn all default autovivification off in my
> >> program, but that's not possible.)
> >
> > I am not sure I know what you mean by "program", but the NAMESPACE file allows
> > you to declare which functions you want to import from other packages.  I think
> > it is not as strict as you want:  if you don't declare it, you might still find
> > it, but if you do declare it, you'll find that version before any user-created
> > or other-package-created one.
> >
> > It might be a good idea for R to allow a package to request the strict
> > declaration model, where you need to declare *every* import.  I don't know how
> > difficult a change that would be.
>
> This sounds like codetools' findGlobals, which has problems with idioms like
> subset() and with() at least. One would want a general solution for this, rather
> than the current utils::globalVariables.

Actually I was thinking of having the chain of parents of the namespace 
environment stop at the base environment, rather than continuing through 
the base namespace to the global namespace and search path.

I'd guess that would mess pretty seriously with things like S3 and S4 
dispatch, and maybe other things too.

Duncan Murdoch