Skip to content

@hadley hadley released this Oct 29, 2015 · 577 commits to master since this release

New features

  • Roxygen now records its version in a single place: the RoxygenNote
    field in the DESCRIPTION (#338). This will be the last time an roxygen2
    upgrade changes every file in man/.
  • You can now easily re-export functions that you've imported from another
    package:
#' @export
magrittr::`%>%`

All imported-and-re-exported functions will be documented in the same
file (rexports.Rd), containing a brief descrption and links to the
original documentation (#376).

  • You can more easily generate package documentation by documenting the
    special string "_PACKAGE" (@krlmlr, #349):
#' @details Details
"_PACKAGE" 

The title and description will be automatically filled in from the
DESCRIPTION.

  • New tags @rawRd and @rawNamespace allow you to insert raw (unescaped)
    in Rd and the NAMESPACE (this is useful for conditional imports).
    @evalRd() is similar, but instead of literal Rd, you give it R code that
    produces literal Rd code when run. This should make it easier to experiment
    with new types of output (#385).
  • Roxygen2 now parses the source code files in the order specified in the
    Collate field in DESCRIPTION. This improves the ordering of the generated
    documentation when using @describeIn and/or @rdname split across several
    .R files, as often happens when working with S4 (#323, #324).

Minor features and bug fixes

  • The contents of documented functions are now also parsed for roxygen comments.
    This allows, e.g., documenting a parameter's type close to where this type is
    checked, or documenting implementation details close to the source, and
    simplifies future extensions such as the documentation of R6 classes
    (#397, @krlmlr).
  • Data objects get a simpler default @format that describes only the
    object's class and dimensions. The former default, generated by generated by
    str(), didn't usually produce useful output and was quite slow. The new S3
    generic default_data_format() generates the format and can be overridden to
    generate a custom format (#410, @krlmlr).
  • The roxygen parsers has been completely rewritten in C++ (#295). This gives a
    nice performance boost and gives:
    • Better error messages: you now get the exact the line number of the
      tag, not just the start of the block.
    • The parser has been simplified a little: tags now must always start
      on a new line. This is recommended practice anyway, and it means
      that escaping inline @ (with @@) is now optional. (#235)
    • Unknown tags now emit a warning, rather than an error.
  • @examples no longer complains about non-matching braces inside
    strings (#329).
  • @family now cross-links each manual page only once, instread of linking
    to all aliases (@gaborcsardi, #283, #367).
  • The special @include parser has also been rewritten in C++, giving
    a performance boost for larger packages (#401). This is particularly
    important because it's also called from devtools::load_all().
    Additionally, a space before @include is no longer necessary
    (@krlmlr, #342).
  • @inheritParams foo::bar ensures that % remains escaped (#313).
  • If you document multiple arguments with one @param, (e.g. @param a,b,c)
    each parameter will get a space after it so it can be wrapped in the
    generated Rd file (#373).
  • @sections with identical titles are now merged together, just like
    @description and @details. This is useful in conjunction with the
    @rdname tag. (@krlmlr, #300).
  • Automatic @usage is now correctly generated for functions with string
    arguments containing "\"" (#265).
  • load_options() is now exported so devtools::document() doesn't have to
    run update_collate() twice (#395).
  • update_collate() only rewrites the Collate entry in the DESCRIPTION file
    when it changes (#325, #723).
  • An empty NAMESPACE file is written if it is maintained by roxygen2
    (@krlmlr, #348).
  • Data that is not lazy-loaded can be documented (@krlmlr, #390).

Internal changes

  • register.preref.parser() and register.preref.parsers() have been
    deprecated - please use register_tags() instead.
  • Parser callbacks registered with register_tags() are now called for fields
    parsed from the "introduction" (the text before the first tag)
    (@gaborcsardi, #370).
Assets 2
You can’t perform that action at this time.