I have written an R package for integrating with electronic medical records. I think I have correctly added the imports and dependencies in the DESCRIPTION file and documented everything via roxygen2, but on three of my functions (which are all in the same file) I get this warning when I run devtools::check("."):
* checking for missing documentation entries ... WARNING
Undocumented code objects:
'add_to_database' 'database' 'import_CPRD_data'
All user-level objects in a package should have documentation entries.
I think I have documented these in the same way as all of my other functions which are fine. Here is one of the offending functions with the roxygen2 documentation:
#' Wrapper for dbconnect
#'
#' Connects to a SQLite database or creates one if it does not already exist
#'
#' If the '.sqlite' file extension is ommited from the dbname argument it is automatically added.
#'
#' #export
#'
#' #param dbname character name path to database file
#' #return SQLiteConnection object
#' #examples \dontrun{
#' db <- database("mydb")
#' }
database <- function(dbname){
if(!str_detect(dbname, "\\.sqlite$")) {
dbname <- paste(dbname, "sqlite", sep = ".")
}
dbConnect(SQLite(), dbname)
}
How can I get rid of this error? I have added stringr and RSQLite to the depends section of the DESCRIPTION file and they show up in NAMESPACE, so I don't think this is an import problem - but then what am I failing to document? The full package is here and the file with the file with the offending functions is here. I have looked in the writing R extensions manual and can't find the problem - don't know if I am just going blind from looking - but I can't see what I am doing differently in these functions from the others I have written!
You use roxygen, but most likely you don't roxygenize your package on build.
Either call:
roxygen2::roxygenize('.', roclets=c('rd', 'collate', 'namespace'))
or, if you use RStudio, edit Project Options (Tools menu) and in the Build Tools tab check Generate documentation with Roxygen.
I have had a similar problem when doing an R CMD check:
Status: 1 WARNING
checking for missing documentation entries ... WARNING
Undocumented code objects:
‘build.log.output’
After removing all files step-by-step I have found the reason: The .Rbuildignore file! It contained (besides other lines) one line with
^.*\.log
The last line makes R ignoring all files containing a ".log" in its name and my function was named "build.log.output" which caused R to ignore the documentation file "build.log.output.Rd" generated by Roxygen2 when creating the package file.
Therefore R CMD check could not find the documentation in the package file!
Solution:
Improve the regular expression to ignore only real log files:
^.*\.log$
("$" means matching the end of line).
Voila :-)
EDIT:
#R Yoda solved the problem stated in my "answer": It was related to a conflict between .Rbuildignore and the function name (more precisley, the file name of the function's documentation).
Same problem here. And for me, it was related to the name of the function. When the name of the function below is load_rdata (or loadrdata), I receive the warning Undocumented code objects: 'load_rdata'. When I rename the function to load_rda, everything is fine.
I know this is half a question (why is this happening), half an answer (maybe because of the function names), but I thought it might help somebody coming across this question.
#' Load RData file.
#'
#' #param file An RData file saved via \code{\link[base]{save}}.
#' #return The object save in \code{file}.
#' #references \url{http://stackoverflow.com/a/5577647}
#' #export
load_rdata <- function(file = NULL) {
env <- new.env()
nm <- load(file, env)[1]
env[[nm]]
}
This is the output from sesssionInfo() and was reproducible when using devtools 1.12.0 and roxygen2 6.0.0 instead.
R version 3.3.2 (2016-10-31)
Platform: x86_64-w64-mingw32/x64 (64-bit)
Running under: Windows >= 8 x64 (build 9200)
locale:
[1] LC_COLLATE=German_Germany.1252 LC_CTYPE=German_Germany.1252 LC_MONETARY=German_Germany.1252
[4] LC_NUMERIC=C LC_TIME=German_Germany.1252
attached base packages:
[1] stats graphics grDevices utils datasets methods base
other attached packages:
[1] devtools_1.12.0.9000 roxygen2_6.0.0.9000
loaded via a namespace (and not attached):
[1] R6_2.2.0 magrittr_1.5 tools_3.3.2 withr_1.0.2 memoise_1.0.0
[6] Rcpp_0.12.9 xml2_1.1.1 stringi_1.1.2 pkgload_0.0.0.9000 digest_0.6.12
[11] stringr_1.1.0 pkgbuild_0.0.0.9000 commonmark_1.1
I ran across the undocumented code error when I had multiple functions to export. I think you need to add #' #describeIn. Here's my example.
#' #title Colors Definition
#'
#' #description Define colors with transparency value.
#'
#' #param alpha Transparency value (0-1), default 1.
#'
#' #return hex value of the color
#'
#' #examples
#' Get_Red(0.5)
#' Get_Red()
#'
#' #export Get_Red
#' #export Get_Blue
#'
Get_Red <- function(alpha = 1) {
rgb(228 / 255, 26 / 255, 28 / 255, alpha)
}
#' #describeIn Get_Red Blue color function with transparency value.
Get_Blue <- function(alpha = 1) {
rgb(55 / 255, 126 / 255, 184 / 255, alpha)
}
I was experimenting with the toy foofactors package in Hadley Wickam's book. My data.R file included:
#' A character string
#'
"MyString"
and fbind.R had:
#' Print a string
#'
#' Returns the string MyString
#'
#' #export
#'
myString <- function() {
print(foofactors::MyString)
}
check complained that there was undocumented code and data. I fixed this by chnaging the function name to theString. So it appears that the names are not case sensitive which is odd.
After several frustrating hours, I found that I had man/ in my .Rbuildignore file. 🤦
I fixed this same error message by installing the devtools package.
In my case, I had created a new package on a new laptop and installed all the usual R packages and accessories: installr, testthat, roxygen2 and also the accessory tools like rtools and MiKteX. When building the package I got the same error message "checking for missing documentation entries ... WARNING: Undocumented code objects". But I fully resolved the problem by also installing the devtools package.
Related
for some reason pkgdown is failing to parse one of the .Rd files that I have in my package. I found it fails when I add examples to the roxygen2 documentation using either the #examples tag or the #example inst/example/add.R alternative. I minimized my function to two arguments in order to make it more "reproducible" and still getting the same error. Please find bellow the error message, the .Rd file generated using that devtools::document() and the roxygen2 documentation of the function. As you can see I am using a very simple example that should run with no problems... One more thing to say is that when I run devtools::check() all my examples pass, so I don't understand why pkgdown is failing.
Thank you so much for your help.
Best,
Error message
Reading 'man/merge.Rd'
Error : Failed to parse Rd in merge.Rd
i unused argument (output_handler = evaluate::new_output_handler(value = pkgdown_print))
Error: callr subprocess failed: Failed to parse Rd in merge.Rd
i unused argument (output_handler = evaluate::new_output_handler(value = pkgdown_print))
.Rd file
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/merge.R
\name{merge}
\alias{merge}
\title{Merge two tables}
\usage{
merge(x, y)
}
\arguments{
\item{x}{data frame: referred to \emph{left} in R terminology, or \emph{master} in
Stata terminology.}
\item{y}{data frame: referred to \emph{right} in R terminology, or \emph{using} in
Stata terminology.}
}
\value{
a data.table joining x and y.
}
\description{
This is the main and, basically, the only function in joyn.
}
\examples{
x <- c(1, 2)
}
roxygen2 documentation
#' Merge two tables
#'
#' This is the main and, basically, the only function in joyn.
#'
#' #param x data frame: referred to *left* in R terminology, or *master* in
#' Stata terminology.
#' #param y data frame: referred to *right* in R terminology, or *using* in
#' Stata terminology.
#' #return a data.table joining x and y.
#' #export
#' #import data.table
#'
#' #examples
#' x <- c(1, 2)
This error comes from downlit::evaluate_and_highlight (sad it's not reported in the output), and can be fixed by installing the development version of downlit:
library(devtools)
install_github('r-lib/downlit')
It make sense only if you use the git version also from pkgdown, the stable pkgdown (version 1.6.1) runs just fine with the stable downlit. Of course development version of any package can break at any time, but until it doesn't, it's just alright.
I'm trying to create a S3 method in my package called dimnames. This is a primitive in R, but there should be an S3 in my package with the same name.
I've got the following file dimnames.r
#' S3 overwriting primitive
#'
#' #param x object
#' #export
dimnames = function(x) {
UseMethod("dimnames")
}
#' title
#'
#' #export
dimnames.data.frame = function(x) {
dimnames.default(x)
}
#' title
#'
#' #export
dimnames.list = function(x) {
lapply(x, dimnames)
}
#' title
#'
#' #export
dimnames.default = function(x) {
message("in S3 method")
base::dimnames(x)
}
I then create a package from it (in R=3.3.2):
> package.skeleton("rpkg", code_files="dimnames.r")
> setwd("rpkg")
> devtools::document() # version 1.12.0
And then check the package
R CMD build rpkg
R CMD check rpkg_1.0.tar.gz
I get the following output (among other messages):
Warning: declared S3 method 'dimnames.default' not found
Warning: declared S3 method 'dimnames.list' not found
Loading the package and checking its contents, dimnames.data.frame is exported while dimnames.default and dimnames.list are not. This does not make sense to me. As far as I understand, I declared the exports correctly. Also, the NAMESPACE file looks good to me:
S3method(dimnames,data.frame)
S3method(dimnames,default)
S3method(dimnames,list)
export(dimnames)
Why does this not work, and how to fix it?
(Bonus points for: why do I need #' title in the S3 implementations when they should not be needed with roxygen=5.0.1?)
S3 methods are only exported if it is desired that the user be able to access them directly. If they are always to be invoked via the generic then there is no need to export them.
The problem with R CMD check is likely due to defining your own generic for dimnames. Normally one just defines methods and leverages off the primitive generic already in R. Remove the dimnames generic from dimnames.r.
There should be no problem in adding methods for new classes but you may have problems trying to override the functionality of dimnames for existing classes that R's dimnames handles itself.
I am writing an R package and create documentation using roxygen2. I build the package and the documentation using the button Build & Reload in RStudio. According to RStudio's output, it uses devtools::document(roclets=c('rd', 'namespace')) to compile the documentation.
I want to use the #family tag to link together a number of functions in the documentation and this is where my problem occurs. This line
#' #family functions returning some object
is converted in the .Rd file to the following
\seealso{
Other functions.returning.some.object: \code{\link{test2}}
}
I don't want the dots between the words. I have an older package, where this does not happen, even if I recompile the documentation in the exact same setting as I compile the new package. I can see no fundamental difference between this older package and my new attempt.
I have written a very simple test package, where the problem also occurs. It contains a single R file (testpackage.R):
#' Test function 1
#'
#' #param x a number
#'
#' #family functions returning some object
#' #family aggregate functions
#'
#' #export
test1 <- function(x) {
x*x
}
#' Test function 2
#'
#' #param x a number
#'
#' #family functions returning some object
#' #family aggregate functions
#'
#' #export
test2 <- function(x) {
x*x*x
}
The DESCRIPTION file is
Package: testpackage
Type: Package
Title: Package for testing purposes
Version: 1.0
Date: 2015-05-21
Author: Me
Maintainer: Me <me#somewhere.com>
Description: Package for testing purposes
License: GPL-3
NAMESPACE is generated by roxygen. For the documentation test1.Rd, I get:
% Generated by roxygen2 (4.1.1): do not edit by hand
% Please edit documentation in R/testpackage.R
\name{test1}
\alias{test1}
\title{Test function 1}
\usage{
test1(x)
}
\arguments{
\item{x}{a number}
}
\description{
Test function 1
}
\seealso{
Other aggregate.functions: \code{\link{test2}}
Other functions.returning.some.object: \code{\link{test2}}
}
with the unwanted dots in the \seealso section. Clearly, the number of words in the #family tag seems not to matter. I have tried enclosing the text in quotation marks, various kinds of brackets, etc. with no positive effect. Of course, I could edit the Rd files, but this would miss the point of using roxygen2.
R CMD check runs without warnings or errors on testpackage.
Why do these dots appear? And how can I get rid of them?
This is a bug in roxygen2 -- I've logged an issue here. It effectively results from the use of unstack(), which performs some unwanted conversions.
I upgraded to Roxygen 5.0.0 (which is now the CRAN version) and found that the problem went away.
To demonstrate a minimal case, say I have the following package:
#' #docType package
#' #import methods
#' #title MyTitle
#' #description MyDescription
#' #details MyDetails
#' #export
A <- setRefClass("A")
When I roxygenize (in RStudio, before a 'Build & Reload'). I get:
==> roxygenize('.', roclets=c('rd', 'collate', 'namespace'))
* checking for changes ... ERROR
Error in process.docType(partitum) :
Roclet processing error in block Test1.R:7
argument is of length zero
What's going wrong? How do I resolve this error?
My setup:
Roxygen2 3.1.0
Using roxygen to generate (in RStudio):
Rd files
Collate field
NAMESPACE file
Automatically roxygenising when running (in RStudio):
R CMD check
Source and binary package builds
Build & Reload
R: 3.0.2 (Frisbee Sailing)
IDE: RStudio 0.98.490
OS: Windows 8.1
I had a similar situation where
#' #export
A <- setRefClass("A")
cause the same error, which I resolved using:
A <- setRefClass("A")
#' #export
A
Curiously, this was in a file that I had not modified in a while, so it's still a bit of a mystery...
I am new to roxygen and am struggling to see how to be able to use it to quickly create a new/custom package.
I.e. I would like to know the minimum requirements are to make a package called package1 using devtools, roxygen2/3 so that I can run the commands
require(package1)
fun1(20)
fun2(20)
to generate 2000 and 4000 random normals respectively
So lets take the simplest example.
If I have two functions fun1 and fun2
fun1 <- function(x){
rnorm(100*x)
}
and
fun2 <- function(y){
rnorm(200*y)
}
the params are numeric, the return values are numeric. I'm pretty sure this isn't an S3 method, lets call the titles fun1 and fun2....im not too sure what other info i would need to provide. I can put fun1 and fun2 in separate .R files and add abit of #' but am unsure to include all relevant requirements for roxygen and also am unsure what to include as relevant requiremetns and how to use it to create the rd documentation to go with a package are. I presume the namespace would just have the names fun1 and fun2? and the package description would just be some generic information relating to me...and the function of the package?
any step by step guides would be gladly received.
EDIT: The below is how far I got to start with...
I can get as far as the following to create a pacakge...but cant use roxygen to make the documentation...
package.skeleton(list = c("fun1","fun2"), name = "package1")
and here is where I am not sure if I am missing a bunch of steps or not...
roxygenise("package1")
so when trying to install i get the following error message
system("R CMD INSTALL package1")
* installing to library ‘/Library/Frameworks/R.framework/Versions/2.15/Resources/library’
* installing *source* package ‘package1’ ...
** R
** preparing package for lazy loading
** help
Warning: /path.to.package/package1/man/package1-package.Rd:32: All text must be in a section
*** installing help indices
Error in Rd_info(db[[i]]) :
missing/empty \title field in '/path.to.package/package1/man/fun1.Rd'
Rd files must have a non-empty \title.
See chapter 'Writing R documentation' in manual 'Writing R Extensions'.
* removing ‘/Library/Frameworks/R.framework/Versions/2.15/Resources/library/package1’
I'm surprised #hadley says to not use package.skeleton in his comment. I would use package.skeleton, add roxygen comment blocks, then delete all the files in the "man" directory and run roxygenize. However, since Hadley says "Noooooooooo", here's the minimum you need to be able to build a package that passes R CMD check and exports your functions.
Create directory called "package1". Under that directory, create a file called DESCRIPTION and put this in it (edit it appropriately if you like):
DESCRIPTION
Package: package1
Type: Package
Title: What the package does (short line)
Version: 0.0.1
Date: 2012-11-12
Author: Who wrote it
Maintainer: Who to complain to <yourfault#somewhere.net>
Description: More about what it does (maybe more than one line)
License: GPL
Now create a directory called "R" and add a file for each function (or, you can put both of your functions in the same file if you want). I created 2 files: fun1.R and fun2.R
fun1.R
#' fun1
#' #param x numeric
#' #export
fun1 <- function(x){
rnorm(100*x)
}
fun2.R
#' fun2
#' #param y numeric
#' #export
fun2 <- function(y){
rnorm(200*y)
}
Now you can roxygenize your package
R> library(roxygen2)
Loading required package: digest
R> list.files()
[1] "package1"
R> roxygenize("package1")
Updating collate directive in /home/garrett/tmp/package1/DESCRIPTION
Updating namespace directives
Writing fun1.Rd
Writing fun2.Rd
Since you mentioned devtools in the title of your Q, you could use the build and install functions from devtools
build('package1')
install('package1')
Or you can exit R and use the tools that come with R to build/check/install.
$ R CMD build package1
$ R CMD check package1_0.0.1.tar.gz
$ R CMD INSTALL package1_0.0.1.tar.gz
Now, fire up R again to use your new package.
$ R --vanilla -q
library(package1)
fun1(20)
fun2(20)
But, figuring out the minimum requirements is unlikely to help you (or the users of your package) much. You'd be much better off studying one of the many, many packages that use roxgen2.
Here's a better version of the fun1.R file which still doesn't use all the roxygen tags that it could, but is much better than the bare minimum
Modified fun1.R
#' fun1
#'
#' This is the Description section
#'
#' This is the Details section
#'
#' #param x numeric. this is multiplied by 100 to determine the length of the returned vector
#' #return a numeric vector of random deviates of length \code{100 * x}
#' #author your name
#' #seealso \code{\link{fun2}}
#' #examples
#' fun1(2)
#' length(fun1(20))
#' #export
fun1 <- function(x){
rnorm(100*x)
}
Much later - You could let RoxygenReady prepare your functions with the minimal Roxygen annotation skeleton. It basically brings you from your 2 input functions to GSee's answer, which is the input of Roxygen2.