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.we...@gmail.com)
______________________________________________
R-help@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@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
______________________________________________
R-help@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.
