[Roxygen-devel] Roxygen2: version 2.2

[Hadley Wickham]

# Roxygen2

The premise of `roxygen2` is simple: describe your functions in
comments next to where their definitions and `roxygen2` will process
your source code and comments to produce R compatible Rd files.
Here's a simple example from the `stringr` package:
? ? #' The length of a string (in characters).? ? #'? ? #' @param
string input character vector? ? #' @return numeric vector giving
number of characters in each element of the?? ? #' ? character vector.
?Missing string have missing length.? ? #' @keywords character? ? #'
@seealso \code{\link{nchar}} which this function wraps? ? #' @export
#' @examples? ? #' str_length(letters)? ? #' str_length(c("i",
"like", "programming", NA))? ? str_length <- function(string) {
string <- check_string(string)
? ? ? nc <- nchar(string, allowNA = TRUE)? ? ? is.na(nc) <-
is.na(string)? ? ? nc? ? }
When you `roxygenise` your package these comments will be
automatically transformed to the Rd file you need to pass `R CMD
check`:
? ? \name{str_length}? ? \alias{str_length}? ? \title{The length of a
string (in characters).}? ? \usage{str_length(string)}? ? \arguments{
? ? \item{string}{input character vector}? ? }? ? \description{
The length of a string (in characters).? ? }
\seealso{\code{\link{nchar}} which this function wraps}
\value{numeric vector giving number of characters in each element of
the? ? character vector. ?Missing string have missing length.}
\keyword{character}? ? \examples{? ? ? str_length(letters)
str_length(c("i", "like", "programming", NA))? ? }
roxygen2 2.2
------------

NEW FEATURES

* Package docType will automatically add package alias, if needed. (Fixes #4)

* Data docType will automatically add `datasets` keyword, default usage, and
default format. (Fixes #5). Data docType automatically added to data
objects.

* New `@encoding` tag for manually setting non-ASCII encodings when needed.
(Fixes #7)


BUG FIXES

* `write.description()` now tries much harder to respect
users' original DESCRIPTION field formatting instead of forcibly
re-wrapping certain fields at 60 characters.

* `@details` and `@description` now work correctly

* `@useDynLib` now works correctly:

@useDynLib packageName routine1 routine2

produces

useDynLib(packageName, routine1)
useDynLib(packageName, routine2)

in the NAMESPACE file, instead of separate (wrong) useDynLib statements as
before.

* All namespace import directives now behave in the same way as the export
directives, producing multiple single directives instead one multiple
directive: `@importClassesFrom pkg a b` now produces
`importClassesFrom(pkg, a)` and `importClassesFrom(pkg, b)`

* In example files included with `@example` you can now use infix operators
(e.g. %*%) or other things with %, because they will be preceded by a
backslash in the Rd file. This behaviour was already in place for examples
directly included with `@examples`.

* Aliases are no longer quoted, and % is escaped with a backslash (Fixes #24).
Names also have % escaped (Fixes #50)

* Replacement functions (e.g. `foo<-`) now get correct usage statements:
`foo() <- value` instead of `foo()<-value`. (Fixes #38)

* Functions with no arguments now correctly get usage statements (Fixes #35)

* Indentation in examples now preserved (Fixes #27)

* roxygen2 will replace characters that are not valid in filenames with a
character substitute, e.g. `[]` becomes `sub`, `<-` becomes `set` (Fixes #6)

* Usage strings use non-breaking spaces to prevent string default values
containing whitespace to be split across multiple lines. This may cause
problems in the unlikely event that you have default value containing a
non-breaking space (`"\uA0"') (Fixes #21)

* Functions with quoted names now get correct usage statements (Fixes #41)

* Objects that no longer exist are not documented (Fixes #42)

* Errors now display file name and line number of roxygen block to help you
find the problem. Thanks to code contributions from Renaud Gaujoux. (Fixes
#13)

* Documentation with no untagged text but with `@title`, `@description` and
`@details` tags now produces correct output.