[Roxygen-devel] Roxygen2 4.0.0

[Hadley Wickham]

Hi all,

I'll getting ready to release a new version of roxygen2 in the next
couple of weeks. It contains vastly improved error handling and two
useful new tags. If you use roxygen2, I'd appreciate your feedback.
Try the dev version out by running
devtools::install_github("klutometis/roxygen"). Complete news below.

Regards,

Hadley


# roxygen2 4.0.0

Roxygen2 4.0.0 is a major update to roxygen2 that makes provides
enhanced error handling and considerably safer default behaviour. Now,
roxygen2 will never overwrite a file that it did not create. This
means that before you run it for the first time, you'll need to all
files generated by previous versions of roxygen2, including
`NAMESPACE` and `man/*.Rd`

## New features

* Six vignettes provide a comprehensive overview of using roxygen2 in
  practice. Run `browseVignettes("roxygen2")` to access.

* `@describeIn` makes it easier to describe multiple function in
  one file. This is especially useful if you want to document methods with
  their generic, or with a common class, but it's also useful if you want
  to document multiple related functions in one file (#185).

* `@field` documents the fields on a reference class (#181). It works the
  same way as `@slots` for S4 classes.

* Roxygen2 now adds a comment to all generated files so that you know
  they've been generated, and should not be hand edited.

* Roxygen2 no longer wraps the text in Rd files by default, i.e. the default
  option is `wrap = FALSE` now. To override it, you have to specify a field
  `Roxygen: list(wrap = TRUE)` in `DESCRIPTION` (#178).

## Improved error handling

* Roxygen2 will never overwrite a file that was not generated by
  roxygen2. This means that the first time you use this version of
  roxygen, you'll need to delete all existing Rd files. `roxygenise()`
  gains a clean argument that will automatically remove any files
  previously created by roxygen2.

* Parsing is stricter: many issues that were previously warnings are
  now errors. All errors should now give you the line number of the
  roxygen block associated with the error.

* Every input is now checked to make sure that you have matching braces
  (e.g. every `{` has a matching `}`). This should prevent frustrating
  errors that require careful reading of `.Rd` files (#183).

* `@section` titles and `@export` tags can now only span a single line
  to prevent common bugs.

* `@S3method` is deprecated - just use `@export` (#198).

* Better error message if you try to document something other than NULL,
  an assignment, a class, a generic or a method (#194).

## Bug fixes and minor improvements

* Remove unneeded codetools and tools dependencies.

* Bump required Rcpp version to 0.11.0, and remove custom makefiles.

* Non-syntactic argument names (like `_x`) are now surrounded by back-ticks
  in the usage (#191).

* The internal parsers are no longer part of the public roxygen2 interface.

* Usage statements in generated roxygen statements non-longer contain
  non-ASCII characters and will be wrapped if long (#180).


-- 
http://had.co.nz/