[Roxygen-devel] Roxygen2 4.0.0 - pre release

[Hadley Wickham]

Hi all,

I'm planning to push roxygen2 4.0.0 to CRAN in the next week or so.
There are three main new features:

* all outputs are flagged with a comment that indicates that roxygen2
produced them, and roxygen2 will not overwrite a file it didn't
create.  (This is the reason it's a major version bump)

* Rd files are no longer wrapped by default

* vignettes actually explain how to use roxygen2.

I've included the complete release notes below, but I'd really
appreciate if you'd devtools::install_github("klutometis/roxygen") and
try it out on your packages. Please let me know if you encounter any
new problems, or find the upgrade process confusing.

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 run
`roxygen2::upgradeRoxygen()`. That will flag all existing files as
being created by roxygen2.

## 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 `@slot` 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).

* By default, reference classes now only document their own methods,
  not their methods of parents (#201).

* Default aliases always include the original name of the object, even if
  overridden by `@name`. This also means that `A <- setClass("A")` will get
  two aliases by default: `A` and `A-class` (#202). Use `@aliases NULL` to
  suppress default alias.

* Non-syntactic class names (like `<-`) are now escaped in the usage
  section of S4 methods (#205).


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