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)")
})

Mallard is a markup language for help files. Could be a target of Roxygen.
http://projectmallard.org/

If .Rbuildignore has an entry related to files in R/, the collate roclet should ignore these files as well.

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.

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.

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.

For conveniently documenting defunct and deprecated functions.

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")
})

Only challenge is figuring out where generic is - current package or another package.

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")
})

Since other roclets depend on the code being loaded in the correct order

Should automatically create the right aliases

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.

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.

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:

• checking package subdirectories ... WARNING
  Subdirectory ‘inst’ contains no files.

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)

From @imports, @importsFrom etc.

Roxygen should use default collation if Collate field not present in DESCRIPTION.

easy fix: https://github.com/klutometis/roxygen/blob/master/R/roclet-rd.R#L540

see file.show(file.path(R.home('doc'), 'KEYWORDS'))

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.

Does roxygen know to look in sub directories of /R? Or does it expect only the traditional package.skeleton() structure?

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.

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

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 = "/")

A roclet which creates the demo/00index file based on a "@demo description" tag in the .R demo files.

currently roxygen2 generates usage like foo<-(x, value) for a function 'foo<-' <- function(x, value), but it really should be foo(x) <- value

Can roxygen2 parse the DESCRIPTION file and automatically load packages in the Depends and Imports fields when roxygenizing a package?

Roclet which enables bibtex citations; e.g.,

' @references

' @bibitem Venables+Ripley-2002

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.

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.

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(".")

sorry this can be deleted..

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.

So you can find where the error occurred. Should be straightforward to implement since partita has all needed srcref info.

Background

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.

Steps to reproduce the problem

1. clone down the granovaGG github repository. At a terminal, type:

   git clone [email protected]:briandk/granovaGG.git
   

2. Navigate into your local granovaGG repository and check out this commit (again at a terminal)

   git checkout 80f8f0022ea1a445d434f7211a5c5e249bbed201
   

3. 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")
   

Expected Behavior

Nothing. The package has already been run through roxygenize, and the author list is formatted as I'd like it. Nothing should change.

Actual Behavior

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:

Roclet which adds a field "Build-Depends" in the DESCRIPTION file with roxygen2 (and additional packages like testthat, devtools, etc. if used).

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.

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?

It would be nice if there was a way to preserve formatting in examples section. Right now all leading spaces are eaten :(

Should automatically:

• @keyword dataset
• @format X by X data frame
• @usage mydata

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:

' @name show

' @Aliases show show,helloworld-method

' @doctype methods

' @rdname show-methods

' @export

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):

• checking for missing documentation entries ... WARNING
  Undocumented S4 methods:
  generic 'helloworld' and siglist 'array'
  generic 'helloworld' and siglist 'character'
  generic 'helloworld' and siglist 'function'
  generic 'helloworld' and siglist 'helloworld'
  generic 'helloworld' and siglist 'integer'
  generic 'helloworld' and siglist 'list'
  generic 'helloworld' and siglist 'logical'
  generic 'helloworld' and siglist 'matrix'
  generic 'helloworld' and siglist 'numeric'
  generic 'print' and siglist 'helloworld'
  generic 'show' and siglist 'helloworld'
  All user-level objects in a package (including S4 classes and methods)
  should have documentation entries.

The documentation for useDynLib seems to be missing.
In addition, one page with all tags would be useful in the documentation.

Thanks,

Rainer

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.

R code:

##' foo
##'
##' @param a a
##' @param b b
##' @param c c
foo <- function(a = "sdmldsflkjmsqdlkfjk", b = "fmqlk", c = "\n\np. \n\n") {
  return(NULL)
}

\usage section:

\usage{
  foo(a = "sdmldsflkjmsqdlkfjk", b = "fmqlk", c = "\n\np.
  \n\n")
}

Please not the newline for the 'c' argument.

R cmd check:

* 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"

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