Hello. I am creating an R package that I'd like to submit to CRAN (OS Windows XP). How do I distinguish among 'public' functions, e.g., those that are intended to be called by users of the package and for which I am providing documentation & examples, and 'private' functions, which are used internally by the 'public' functions, but for which I do not wish to provide documentation? The private functions are all coded in R (nothing in C or Fortran) and are essential to the operation of several public functions. I have been unable to find any documentation on this in the 'writing r extensions' manual', on previous posts to R-help, or through any other source. One possibility is to include the source code for the 'private' functions within the public functions. However, since multiple public functions utilize the same core set of 'private' functions, this seems unwieldy and redundant at best. If I simply include the source for the 'private' functions in the "R" directory (without corresponding *.Rd and *.html documentation in /man), then check the package with "R CMD check', it does appear to process the private functions (and successfully builds with R CMD build). However, I do receive a warning for including undocumented code objects. Is this the recommended approach and/or is there a better way to do this? One potential problem with this approach is that - should an error occur within a private function, it may be very difficult for the user to decipher the nature of the problem. Any suggestions will be greatly appreciated. ~Dan Rabosky Dan Rabosky Department of Ecology and Evolutionary Biology 237 Corson Hall Cornell University Ithaca, NY14853-2701 USA DLR32 at cornell.edu web: http://www.birds.cornell.edu/evb/Graduates_Dan.htm
On Wed, 2006-06-07 at 01:14 -0400, Dan Rabosky wrote:> Hello. > > I am creating an R package that I'd like to submit to CRAN (OS Windows > XP). How do I distinguish among 'public' functions, e.g., those that are > intended to be called by users of the package and for which I am providing > documentation & examples, and 'private' functions, which are used > internally by the 'public' functions, but for which I do not wish to > provide documentation? The private functions are all coded in R (nothing > in C or Fortran) and are essential to the operation of several public > functions.Hi Dan, The answer is in the Writing R Extensions manual. You could do either: 1) Put the code for your "private" functions in a file names internal.R. You then provide a simple file named <package-name>-internal.Rd which lists in individual \alias{} markup the names of the private functions, eg; \name{mypackage-internal} \alias{foo1} \alias{foo2} \alias{foo3} \alias{foo4} \title{Internal mypackage Functions} \description{ Internal mypackage functions } \details{ These are not to be called by the user. } \keyword{ internal } But even here, you aren't documenting the internal functions, just working round the package checks. 2) Place your package in a namespace, which is documented fully in Writing R Extensions. Not sure what the best advice is - I'd guess that for all but the simplest packages, namespaces are the preferred way, but the internal.R way works just fine also. By the way, in future, questions of this nature are best asked on the R-Devel list, not here. HTH, Gavin
Dan Rabosky wrote:> Hello. > > I am creating an R package that I'd like to submit to CRAN (OS Windows > XP). How do I distinguish among 'public' functions, e.g., those that are > intended to be called by users of the package and for which I am providing > documentation & examples, and 'private' functions, which are used > internally by the 'public' functions, but for which I do not wish to > provide documentation? The private functions are all coded in R (nothing > in C or Fortran) and are essential to the operation of several public > functions. > > I have been unable to find any documentation on this in the 'writing r > extensions' manual', on previous posts to R-help, or through any other > source. One possibility is to include the source code for the 'private' > functions within the public functions. However, since multiple public > functions utilize the same core set of 'private' functions, this seems > unwieldy and redundant at best. > > If I simply include the source for the 'private' functions in the "R" > directory (without corresponding *.Rd and *.html documentation in /man), > then check the package with "R CMD check', it does appear to process the > private functions (and successfully builds with R CMD build). However, I > do receive a warning for including undocumented code objects. Is this the > recommended approach and/or is there a better way to do this? One > potential problem with this approach is that - should an error occur within > a private function, it may be very difficult for the user to decipher the > nature of the problem. > > Any suggestions will be greatly appreciated. > ~Dan Rabosky > > > > Dan Rabosky > Department of Ecology and Evolutionary Biology > 237 Corson Hall > Cornell University > Ithaca, NY14853-2701 USA > DLR32 at cornell.edu > web: http://www.birds.cornell.edu/evb/Graduates_Dan.htm > > ______________________________________________ > R-help at stat.math.ethz.ch mailing list > https://stat.ethz.ch/mailman/listinfo/r-help > PLEASE do read the posting guide! http://www.R-project.org/posting-guide.htmlit's in the 'extensions' manual, including an example I believe: 1. create a file `NAMESPACE' in the package top level dir (beside `R' and `man') containing the single line exportPattern("^[^\\.]") 2. name all private functions with a leading `.' (more precisely: all functions starting with a `.' are private in this setting). of course, you can modify the pattern to suit another naming convention. joerg