r-lib / roxygen2 Goto Github PK
View Code? Open in Web Editor NEWGenerate R package documentation from inline R comments
Home Page: https://roxygen2.r-lib.org
License: Other
Generate R package documentation from inline R comments
Home Page: https://roxygen2.r-lib.org
License: Other
Having "inst" in the following line of roxygenize:
skeleton <- c(roxygen.dir, file.path(roxygen.dir, c("man", "inst")))
causes a warning in R CMD check if the directory is empty:
Code:
roxygenize(package.dir="/home/beb/Dropbox/dev/package",roxygen.dir="/home/beb/Dropbox/dev/package", copy.package=FALSE, unlink.target=FALSE, overwrite=TRUE)
Error Message:
Error in normalizePath(path, winslash = "/") :
unused argument(s) (winslash = "/")
easy fix: https://github.com/klutometis/roxygen/blob/master/R/roclet-rd.R#L540
see file.show(file.path(R.home('doc'), 'KEYWORDS'))
Here is an example in which usage is NULL
but should really be f()
:
library(roxygen2)
roc <- rd_roclet()
out <- roc_proc_text(roc, "
#' Function without parameters
f <- function() 1")[[1]]
roxygen2:::get_tag(out, "usage")$values
The fix seems to be to remove this line (I'm not sure): https://github.com/klutometis/roxygen/blob/master/R/roclet-rd.R#L405
A roclet which creates the demo/00index file based on a "@demo description" tag in the .R demo files.
Should automatically create the right aliases
It would be nice if there was a way to preserve formatting in examples section. Right now all leading spaces are eaten :(
In various roxygen tutorials I've come across the @slot tag as the suggested tag for documenting each slot of a particular S4 class. However, it seems this is not actually being supported, in this fork or the current CRAN release of roxygen or roxygen2.
I just found a brief mailing-list post declaring that in fact @slot is not supported, and developers should use an itemized list instead. This seems sub-optimal, so I thought I would see if anyone here has a different opinion.
So which is it?
A -- Itemized list?
B -- @slot works, but with some special version of roxygen that I'm unfamiliar with.
C -- Some alternative tag for specifying slots, like @param, that would accomplish the same thing.
Thanks in advance for any help.
Re-implement @nord to not document object
Since other roclets depend on the code being loaded in the correct order
From @imports, @importsFrom etc.
This is true even if the @Usage tag is provided explicitly (although the Usage section could be generated automagically).
I verified with a test package that it only appears to apply to S4 Generic documentation, not vanilla function docs. I solved the issue in my real package by reverting my roxygen2 installation to an older custom fork of roxygen2:
https://github.com/joey711/roxygen
The \Usage{ } section is completely missing from the .Rd files when built using the latest roxygen/klutometis version, but built fine with my older static roxygen2 build.
This is clearly a bug and an S4 issue.
Only challenge is figuring out where generic is - current package or another package.
Roclet which adds a field "Build-Depends" in the DESCRIPTION file with roxygen2 (and additional packages like testthat, devtools, etc. if used).
If generic and class name not supplied, should guess by splitting function name into pieces by fixed(".")
. First piece is generic, last pieces is class name.
If your function statement looks something like
"myfunction" <- function(...)
Then roxygen doesn't create a usage section in the .Rd file. Removing the "" solves the problem.
Mallard is a markup language for help files. Could be a target of Roxygen.
http://projectmallard.org/
Here is a test case:
test_that("don't escape aliases that have already been escaped", {
out <- roc_proc_text(roc, "
#' Title
#' @aliases \\%a\\%
'%a%' <- function(x, y) x + y")[[1]]
expect_equal(format(get_tag(out, "alias")), "\\alias{\\%a\\%}\n")
})
in one of the R files I have something like this, that defines a temporary function in order to define a static variable:
f<- function(){
.a<- 0
function(x=1){
.a<<- .a + x
.a
}
}
f2<- f()
rm(f)
When running roxygenise on this I get the error:
Error in eval(expr, envir, enclos) : object 'f' not found
If on removes the call to rm, there is no error.
> traceback()
12: eval(expr, envir, enclos)
11: eval(assignee, env)
10: parser(call, env)
9: FUN(X[[1L]], ...)
8: lapply(src_refs, parse.srcref, env = env)
7: force(code)
6: parse_cache$compute(c(env_hash, readLines(file, warn = FALSE)),
{
src_refs <- attributes(parse(srcfile$filename, srcfile = srcfile))$srcref
pre_refs <- prerefs(srcfile, src_refs)
if (length(src_refs) == 0)
return(list())
src_parsed <- lapply(src_refs, parse.srcref, env = env)
pre_parsed <- lapply(pre_refs, parse.preref)
stopifnot(length(src_parsed) == length(pre_parsed))
mapply(c, src_parsed, pre_parsed, SIMPLIFY = FALSE)
})
5: FUN("/home/renaud/Documents/tmp/test/R/fun.R"[[1L]],
...)
4: lapply(paths, parse.file, env = env, env_hash = env_hash)
3: unlist(lapply(paths, parse.file, env = env, env_hash = env_hash),
recursive = FALSE)
2: parse.files(r_files)
1: roxygenise(".")
For docType data, the usage is removed for some reason, which is not a correct behaviour. Here is a test case (usage becomes NULL
):
test_that("@docType data does not remove @usage", {
out <- roc_proc_text(roc, "
#' Title.
#'
#' @name abc
#' @docType data
#' @usage data(abc)
NULL")[[1]]
expect_equal(get_tag(out, "usage")$values, "data(abc)")
})
Currently aliases are escaped, but names are not. Here is a test case:
roc <- rd_roclet()
test_that("names escaped, not quoted", {
out <- roc_proc_text(roc, "
#' Title
'%a%' <- function(x, y) x + y")[[1]]
expect_equal(format(get_tag(out, "name")), "\\name{\\%a\\%}\n")
})
Roxygen should use default collation if Collate
field not present in DESCRIPTION.
see http://www.r-project.org/nosvn/R.check/r-oldrel-macosx-ix86/roxygen2-00check.html
I think the problem was introduced by 69006f9 which did not take the R version into consideration, but this is not really a big deal.
This affects especially S4 method documentation, which has an alias naming convention that builds on the generic using no-space commas as delimiter to indicate the signature, and ending with "-method" without the quotes. (http://cran.r-project.org/doc/manuals/R-exts.html#Documenting-S4-classes-and-methods)
The quotes are probably necessary during internal text-handling, but need to be removed from the final \alias{ } tag in the Rd file.
The following example S4 extension of the "show" method illustrates the problem:
setMethod("show", "helloworld", function(object){
cat("Hello World!")
cat("\n")
})
Is translated by the latest version of roxygen2 to the following Rd file:
\docType{methods}
\name{show}
\alias{"show,helloworld-method"}
\alias{show}
\title{Show the helloworld class to standard output.}
\arguments{
\item{object}{A \code{helloworld} object.}
}
I have also created an example package and put on github: ( https://github.com/joey711/testpkg ) . It builds and loads fine, but throws the following errors during because the S4 methods appear undocumented (even though they are):
I guess this is why the Windows binary is unavailable on CRAN: http://cran.r-project.org/web/checks/check_results_roxygen2.html
It looks like a problem of dealing with path names. Is 69006f9 supposed to correct this problem?
Should automatically:
@keyword dataset
@format X by X data frame
@usage mydata
If .Rbuildignore has an entry related to files in R/, the collate roclet should ignore these files as well.
The documentation for useDynLib seems to be missing.
In addition, one page with all tags would be useful in the documentation.
Thanks,
Rainer
library(gsubfn)
library(functional)
##' Substitutions of questionable characters with a hacker-joke to
##' boot.
substitutions=c(
`!`='bang',
`"`='quote',
`#`='hash',
`$`='cash', # sigil
`%`='grapes',
`&`='and',
`'`='single-quote',
`(`='open-paren',
`)`='close-paren',
`*`='star',
`+`='plus',
`,`='comma',
`-`='dash',
`.`='dot',
`/`='slash',
`:`='colon',
`;`='semi-colon',
`<`='less-than',
`=`='equals',
`>`='greater-than',
`?`='p',
`@`='asperand',
`[`='open-brace',
`\\`='backslash',
`]`='close-brace',
`^`='hat',
`_`='sub',
'`'='backtick', # let's add another ` to
# rectify syntax highlighting
# in emacs; thanks.
`{`='open-curly',
`|`='pipe',
`}`='close',
`~`='not'
)
##' \code{NULL} if empty-string.
##' @param string string to check
##' @return \code{NULL} or identity
nil_if_lambda <- function(string)
if (nchar(string)) string else NULL
##' Translate file-system-questionable characters (i.e. punctuation
##' within ASCII).
##' @param filename the filename to translate
##' @return the translated filename
translate_questionable_characters <- function(filename)
do.call(Curry(paste, collapse="-"),
strapply(filename,
pattern='([[:punct:]]|)([^[:punct:]]*|)',
function(punctuation, letters)
c(substitutions[nil_if_lambda(punctuation)],
nil_if_lambda(letters))))
translate_questionable_characters('%||%')
Does roxygen know to look in sub directories of /R? Or does it expect only the traditional package.skeleton() structure?
For conveniently documenting defunct and deprecated functions.
it seems that aliases are quoted when they contain special characters; I looked at the the documentation of %in%
, its alias was \%in\%
(no quotes but %
was escaped). The alias for substr<-
is not quoted either.
The documentation for useDynLib seems to be missing.
In addition, one page with all tags would be useful in the documentation.
Thanks,
Rainer
i.e. if it's already set, or the @include
tag is used somewhere.
e.g. Tour$methods()
in https://github.com/ggobi/cranvas/blob/master/R/qtourr.R
it will be parsed as $(Tour, methods, ...)
, and $
is not registered in srcref.parsers
(the error comes from parse-srcref.R)
I currently don't expect roxygen to write out the "Author" field of my package DESCRIPTION. And, back in April @hadley explained that roxygen only writes the collate directive of a DESCRIPTION file.
But I'm running roxygen 2.1 (from CRAN), and as far as I can tell it's re-writing my author field. Below, I've included steps to reproduce the problem, as well as a screenshot of the diff that results. I apologize that reproducing the problem requires cloning down my git repository.
clone down the granovaGG github repository. At a terminal, type:
git clone [email protected]:briandk/granovaGG.git
Navigate into your local granovaGG repository and check out this commit (again at a terminal)
git checkout 80f8f0022ea1a445d434f7211a5c5e249bbed201
From a clean R session, run the following commands, replacing path/to/local/repository
with the actual path to your local granovaGG repository:
library(roxygen2)
roxygenize("path/to/local/repository")
Nothing. The package has already been run through roxygenize
, and the author list is formatted as I'd like it. Nothing should change.
roxygenize
seems to rewrite the DESCRIPTION file. Running step 3 above produces this output in an R session:
> roxygenize("granovaGG")
Updating collate directive in [redacted]/granovaGG/DESCRIPTION
And examining the diff in files shows:
When there is a default argument of class character, there is sometimes a extra "\n" character in the \usage section which leads to a "Mismatches argument default value" warning in R CMD check.
##' foo
##'
##' @param a a
##' @param b b
##' @param c c
foo <- function(a = "sdmldsflkjmsqdlkfjk", b = "fmqlk", c = "\n\np. \n\n") {
return(NULL)
}
\usage{
foo(a = "sdmldsflkjmsqdlkfjk", b = "fmqlk", c = "\n\np.
\n\n")
}
Please not the newline for the 'c' argument.
* checking for code/documentation mismatches ... WARNING
Codoc mismatches from documentation object 'foo':
foo
Code: function(a = "sdmldsflkjmsqdlkfjk", b = "fmqlk", c = "\n\np.
\n\n")
Docs: function(a = "sdmldsflkjmsqdlkfjk", b = "fmqlk", c = "\n\np.\n
\n\n")
Mismatches in argument default values:
Name: 'c' Code: "\n\np. \n\n" Docs: "\n\np.\n \n\n"
Can roxygen2 parse the DESCRIPTION file and automatically load packages in the Depends and Imports fields when roxygenizing a package?
I often write \code{\link[pkg]{function_name}}
in the documentation, so I would love to see something like @link pkg:function_name
in roxygen (when pkg
is omitted, we just generate \code{\link{function_name}}
). This is similar to @family
but allows cross references to other packages. If @link
is implemented, we may want it to be automatically put into \seealso{}
as well.
Currently it is still not completely clear to me how to register a custom parser like this.
So you can find where the error occurred. Should be straightforward to implement since partita has all needed srcref info.
This gives S3method(plot,\"function\")
but function
should not be quoted:
roc = namespace_roclet()
roc_proc_text(roc,"#' @S3method plot function\nNULL")
It is caused by an unnecessary call to quote_if_needed()
, I think.
Roclet which enables bibtex citations; e.g.,
Somewhere on the way to the final Rd file, the @bibitem tag should be replaced with the corresponding bibtex-entry:
Venables and Ripley. Modern Applied Statistics with S. Springer. ISBN 0-387-95457-0, 2002.
This bug is described at in this StackOverflow question and exists both in the roxygen
and roxygen2
packages.
A demonstratation can be downloaded from here.
I guess this is not commonly used, but we may want to implement it as well. Currently I do not know how to do it, since it involves with nested parsing: @subsection
can be nested within other sections.
currently roxygen2
generates usage like foo<-(x, value)
for a function 'foo<-' <- function(x, value)
, but it really should be foo(x) <- value
sorry this can be deleted..
A declarative, efficient, and flexible JavaScript library for building user interfaces.
π Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. πππ
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google β€οΈ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.