Does the name of the .R and .rd files (documentation) need to have the exact same name as the function it refers to?
For example, can I have a function called "b" and another one called "B" within the same R package and write the documentation into different .R and .rd files?
I'm a bit confused and I wasn't able to find someone encountering the same problem (I even looked it up on DataCamp's course), so thanks in advance.
Best regards!
As the .R file can contain many functions, it doesn't need to have the same exact name as the function(s) it refers to.
Regarding the .Rd files, it's much easier/efficient/practical to let Roxygen turn specially formatted comments into .Rd files.
On Windows (files not case sensitive) avoid to use Upper case / lower case to distinguish functions, because the .Rd file of one of the functions will be overwritten:
Updating package documentation
Loading package
Writing NAMESPACE
Writing FOO.Rd
Writing foo.Rd
#' foo
#'
#' A function to print bar
#'
#' #param bar
#'
#' #return prints input
#' #export
#'
#' #examples
#' foo(1)
#'
foo <- function(bar) { print(bar) }
#' FOO
#'
#' Another function to print bar
#'
#' #param bar
#'
#' #return prints input
#' #export
#'
#' #examples
#' foo(1)
#'
FOO <- function(bar) { print(bar) }
?foo
Related
I'm putting some R code together in a package, and struggling with namespace + import/export problems. It seems that whether or not I add an #' #export line in roxygen, the functions are still visible to the user. So if I have this file:
#' Function I want the user to see
#'
#' A description
#'
#' #param X a parameter
#' #return the same thing
#' #export
external_function<-function(X){X}
#' Function I don't want the user to see
#'
#' A description
#'
#' #param X a parameter
#' #return the same thing
internal_function<-function(X){X}
both functions end up being exposed, along with library.dynam.unload and system.file:
It doesn't seem to make any difference whether the functions are in separate files or not - even if all the functions that shouldn't be exposed are in one file, without any that should, they're still appearing.
Relatedly, all functions from other packages which I import are appearing - I don't know whether this is intended behaviour (it certainly isn't what I wanted!) or whether this is part of the same issue.
#' Function I want the user to see
#'
#' A description
#'
#' #param X a parameter
#' #return the same thing
#' #importFrom dplyr %>%
#' #export
external_function<-function(X){X %>% log}
with this line in the DESCRIPTION file:
Imports:
dplyr
results in:
What am I doing wrong? Is there a way to use functions internally without them being exposed to the user?
The problem was with the way I'd loaded the package, using devtools::load_all(). Using devtools::load_all(...,export_all=F) or loading the package without devtools means that only the right functions are exported :).
I am writing a package named foo that defines an S3 class named foo with various S3 methods. I have written a constructor function foo() that returns a foo object. It seemed practical to name the class after the package, and the function after the class, and I hoped that:
package?foo would bring up the package help page.
?foo and ?foo::foo would bring up the function help page.
But what happens is that:
Both package?foo and ?foo bring up the package help page.
Only ?foo::foo brings up the function help page.
Is there a way to give a package and a function the same name that produces my desired behaviour?
Currently I have a file foo_package.R like this:
#' The foo package
#'
#' A very useful package.
#'
#' #docType package
#' #name foo
NULL
and a file foo.R like this:
#' The foo function
#'
#' A very useful function.
#'
#' #param x A data frame.
#' #return A foo object.
#' #export
foo <- function(x) {
structure(x, class = c("foo", "data.frame"))
}
Any hints are appreciated...
Following the second link in #MrFlick's comment, which points to the text under "Packages" in vignette("rd"), I was able to get the expected behaviour.
foo.R is unchanged, but foo-package.R now reads:
#' The foo package
#'
#' A very useful package.
#'
#' #docType package
#' #keywords internal
#' #aliases foo-package
"_PACKAGE"
Now, as desired:
package?foo and ?"foo-package" bring up the package help.
?foo and ?foo::foo bring up the function help.
I'm writing an R package and want to inherit the documentation for two arguments (say x and y) from an old function (say old()) to a new function, new(). The twist is that these two arguments share the same argument description. That is, in old(), function, they were documented in a single line and separated by commas like this:
#' #param x,y Two arguments with the same description
I used the following for new() to inherit these arguments:
#' #inheritParams old
However, when I build the package, the documentation for new() lists x but not y.
Is there a way to inherit multiple arguments like these?
In case anyone else stumbles across this, the answer is that you cannot do this.
This comes from the roxygen2 creator, Hadley Wickham.
It seems that in version 6.1.1 you can with the only drawback that the two variables in new() will have the same description but will be listed separately.
I tried to write a reproducible example just in case.
# roxygen 6.1.1, devtools 2.0.1, usethis 1.4.0
# Select a project folder and do setwd(<project_folder>)
usethis::create_package("inheritanceTest")
setwd("./inheritanceTest")
t = "
#' Hello
#'
#' #param x,y some stuff
#'
#' #return other stuff
#' #export
test_inherit_parent = function(x,y){
print('Hello')
}
#' Hello2
#'
#' #inheritParams test_inherit_parent
#'
#' #return other stuff2
#' #export
test_inherit_child = function(x,y){
print('Hello2')
}
"
fileConn = file("./R/functions.R")
writeLines(t, fileConn)
close(fileConn)
devtools::document()
devtools::load_all(".")
?test_inherit_parent
?test_inherit_child
I'm writing an R package and largely following Hadley's book on the topic. I'm running into a problem with documenting methods for simple generics like print, plot, head, and tail. When I use the #describeIn tag to control where the method documentation goes, I get the nice feature of them showing up in the help file for the main analysis function that returns an object of the given class. The problem is that these generics also show up in the package's index. If I add #keywords internal to the generics, then they are removed from the package's index, but so is the main analysis function (they are in the same .R file). If I document the generics in a separate .R file, then I can gain control over what is and is not in the package's index, but I have two issues: the main analysis function doesn't come first in the Usage section of the help file; and if add the #keywords internal for the generics, this removes the analysis function from the package index too, even though they are documented (in this instance) in separate files. The crux of the problem seems to be that #keywords internal applies to all functions in the given .R file, and maybe even any function referenced in #describeIn, while #describeIn is designed for documenting multiple functions in a given .R file.
For now, I have the analysis function and generics in the same .R file to control where the method documention goes and its ordering in the Usage section, but am not using #keywords internal and leaving the index cluttered.
Here's a rough sketch of an exported analysis function:
#' #inheritParams foo
#' #export
seats <- function(judgeit.object, ...) {
[...omitted...]
class(out.object) <- "judgeit.seats"
return(out.object)
}
And a generic:
#' #describeIn seats Print a \code{\link{seats}} output
#' #keywords internal
#' #export
print.judgeit.seats <- function(x,...) print(x$output,...)
I want the help file for ?seats to look like this:
seats(judgeit.object, ...)
## S3 method for class 'judgeit.seats'
print(x, ...)
## S3 method for class 'judgeit.seats'
head(x, ...)
## S3 method for class 'judgeit.seats'
tail(x, ...)
I do not want print.judgeit.seats, head.judgeit.seats, etc. to appear in the package index, because it quickly becomes very cluttered.
Unfortunately, I am not aware of any easy fix for what you are asking.
Tags and their effect
#export will make your function visible in the global environment. CRAN requires that you document any such functions that is not hidden (i.e. that starts with .).
If you use #describeIn or #rdname, an automatic alias is created. Any alias creates an entry in the index, but points to the same .Rd file. For example, adding
#' #name myfunction
#' #aliases foo foobar`
would create foo and foobar entries in the index, but refer to the myfunction.Rd documentation file. If you try to delete manually the \alias{} in the .Rd file, CRAN will complain.
#describeIn will list the functions in the order they appear in the .R files (if they are documented in multiple files, they are listed according to the alphabetical order of the .R file, then the order of appearance). Reordering your functions can give you what you want.
#keywords internal (along with #export, a title and a description) will have Roxygen create a .Rd file that can be accessed by the user using ?, but will not be visible in the index (if you have only the tags, Roxygen will not create a .Rd file and you will get a warning because your function is not documented).
If you have a #keywords internal in any of the functions calling #describeIn, that function will be masked from the index. This does not apply to all functions in a .R file, only those which are aliases.
#usage requires you to have an alias for each method documented. You can try using instead #section Usage:, but note sections are listed in alphabetical order and the spacing will be larger.
Workaround
If you document a NULL function, you can add the #param you want. and include a multiple lines #Section: Usage field to include (manually) the S3 methods with your comments. Give it a name such as #name Seats (it cannot be the name of the function, otherwise you have ?seats pointing to two different files).
Then, document your function seats with a different #name tag and a different title, and use #internal' to hide it from the user. Use \code{\link{seats}}` to refer to that documentation.
#' Seats
#' Description of the function
#' #param judgeit.object object
#' #param x object from seats
#' #param ... additional arguments
#' #name seats
#' #section Usage:
#' \preformatted{seats(judgeit.object, ...)
#' ## S3 method for class 'judgeit.seats'
#' print(x, ...)
#' ## S3 method for class 'judgeit.seats'
#' head(x, ...)
#' ## S3 method for class 'judgeit.seats'
#' tail(x, ...)}
NULL
#' Seats function
#' #name internal-function
#' #inheritParams seats
#' #export
#' #keywords internal
#' #seealso \code{\link{seats}}
seats <- function(judgeit.object, ...) {
[...omitted...]
class(out.object) <- "judgeit.seats"
return(out.object)
}
#' Print a \code{\link{seats}} output
#'
#' #inheritParams seats
#' #describeIn internal-function
#' #export
print.judgeit.seats <- function(x,...) print(x$output,...)
This way, the user calling ?seats will be pointed to the overall documentation.
I have a package with a combination of S3 and S4 methods (yeah, I know, but try to write an S4 for sort(), as.matrix() and the likes...). So I stick with the classic roxygen2 from CRAN (version 2.2.2)
I've noticed that whatever I try, I can't get the usage tag in the Rd files get filled in automatically. I know I can do that by hand using #usage, but I want to keep it automated, as I have a rather extensive code base and I don't want to miss a tag somewhere by accident.
An example:
#' A small test function
#'
#' This function tests roxygen2
#' #param x that's right, it's called x
#' #param ... some more stuff
#'
#' #rdname testfun-methods
#' #aliases testfun
#' #docType methods
#' #export
setGeneric("testfun",function(x,...) standardGeneric("testfun"))
#' #rdname testfun-methods
#' #aliases testfun,matrix-method
#' #return the matrix minus 1
setMethod("testfun","matrix",function(x,...){x - 1})
#' #rdname testfun-methods
#' #aliases testfun,numeric-method
#' #return a vector plus 1
setMethod("testfun","matrix",function(x,...){x + 1})
If I wrap this in a package, roxygenize using roxygen2 (and RStudio, if that matters), and check the help file, it looks like this:
\docType{methods}
\name{testfun}
\alias{testfun}
\alias{testfun,matrix-method}
\alias{testfun,numeric-method}
\title{A small test function}
\arguments{
\item{x}{that's right, it's called x}
\item{...}{some more stuff}
}
\value{
the matrix minus 1
a vector plus 1
}
\description{
This function tests roxygen2
}
No \usage section to be found...