Skip to content

@hadley hadley released this May 2, 2014 · 854 commits to master since this release

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

  • You can now document objects defined elsewhere (like datasets) by
    documenting their name as a string (#221). For example, to document an
    dataset called mydata, you can do:

      #' Mydata set
      #'
      #' Some data I collected about myself
      "mydata"
  • 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).

  • Roxygenise automatically deletes out-of-date Rd files in man/.

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).
  • Namespace tags now throw parsing errors if you give them bad inputs (#220).
  • 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

  • Better parsing of non-syntactic function names in other packages when
    used in @inheritParams (#236).
  • Deprecated arguments to roxygenise() (roxygen.dir, copy.package,
    overwrite, unlink.target) removed.
  • 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).
  • Eliminated two more cases where wrapping occured even when wrap = FALSE.
Assets 2
You can’t perform that action at this time.