From h.wickham at gmail.com Wed Feb 19 23:34:17 2014 From: h.wickham at gmail.com (Hadley Wickham) Date: Wed, 19 Feb 2014 16:34:17 -0600 Subject: [Roxygen-devel] Roxygen2 4.0.0 Message-ID: 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/ From h.wickham at gmail.com Wed Feb 19 23:49:13 2014 From: h.wickham at gmail.com (Hadley Wickham) Date: Wed, 19 Feb 2014 16:49:13 -0600 Subject: [Roxygen-devel] Roxygen2 4.0.0 In-Reply-To: References: Message-ID: > 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` Just realised that this is a bit of a pain because you often can't source a package without a NAMESPACE. So I've changed the instructions to: 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::upgrade()`. Make sure to backup any hand generated Rd files and restore after the upgrade. Hadley -- http://had.co.nz/