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.
Related
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
Let's say that package A defines and documents foo() and implements it for bar1 objects.
In a new package B, I would like to expand this method and add its support for bar2 objects.
Currently, I start by reexporting the method:
#' #rdname foo
#' #importFrom A foo
#' #export
A::foo
And then went on extending its behaviour:
#' #rdname foo
#' #method foo bar2
#' #export
foo.bar2 <- function(x, newparam = 3.14, ...){
dosomething(x, newparam)
}
Unfortunately, it seems like this creates a conflict upon devtools checking, which returns the following warning:
> checking Rd metadata ... WARNING
Rd files with duplicated name 'reexports':
'foo.Rd'
Rd files with duplicated alias 'reexports':
'foo.Rd'
Thus, I wonder what this the best way of expanding a method without creating conflict in definition or documentation? Can I do this without having to Depend on the package A? Thanks!
I wrote a show() method for the S4 class myclass which I had defined in my package. I generated documentation for class and method with roxygen2. Everything works nicely, except that I get the following warning in R CMD check results:
checking for missing documentation entries ... WARNING
Undocumented S4 methods:
generic 'length' and siglist 'myclass'
How do I go about documenting show generic which I did not write myself?
In the end, using explicit #aliases and #docType tags solved the issue for me. My documentation block now looks like this:
#' Show method for objects of class \code{myclass}.
#'
#' #docType methods
#' #name show-myclass
#' #rdname show-myclass
#' #aliases show-myclass show,myclass-method
#'
#' #param x A \code{myclass} object.
#'
#' #export
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 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...