Hadley Wickham
2014-03-11 16:03:53 UTC
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).
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/
http://had.co.nz/