[R] First R Package --- Advice?

[Martin Morgan]

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.

Martin

>
> Duncan Murdoch
>
>
>>
>> /iaw
>> ----
>> Ivo Welch (ivo.welch at gmail.com)
>>
>> ______________________________________________
>> R-help at r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-help
>> PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
>> and provide commented, minimal, self-contained, reproducible code.
>>
>
> ______________________________________________
> R-help at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-help
> PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
> and provide commented, minimal, self-contained, reproducible code.


-- 
Computational Biology / Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N.
PO Box 19024 Seattle, WA 98109

Location: Arnold Building M1 B861
Phone: (206) 667-2793