[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.


-- 
Assistant Professor / Dobelman Family Junior Chair
Department of Statistics / Rice University
http://had.co.nz/