roxygen2 5.0.1

• Use ls(), not names() to list elements of environment: fixes R 3.1.0
  incompatibility (#422, @kevinushey).
• @export again allows trailing new line (#415).
• Fixed bug in @noRd, where usage would cause error (#418).

roxygen2 5.0.0

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

Roxygen2 4.1.1

• Formatting of the Authors@R field in the DESCRIPTION file is now retained
  (@jranke, #330).
• The collate roclet falls back to base::strwrap() when generating the
  collate field. This makes roxygen2 compatible with the next version of
  stringr.
• New "vignette" roclet. This vignette automatically rebuilds all out of date
  vignettes (#314).
• An off-by-one error in the C++ Roxygen preparser was fixed.
• The new @backref tag makes it possible to override the sourceref for
  R code generators like Rcpp (@krlmlr, #291, #294).

Roxygen2 4.1.0

• If there are no @include tags, roxygen2 leaves the collate field alone.
  This makes it easier to convert an existing project that uses a predefined
  collate, but if you start with @include and later remove them, you'll
  need to also remove the collate field (#302, #303).
• Protected a dir() with sort_c() - If you'd noticed an inconsistency in
  ordering between devtools::document() and devtools::check() this
  was the cause of that.
• Fixed broken regular expression that caused problems with stringr 1.0.0.
• The Authors@R field in DESCRIPTION is now longer wrapped(@krlmlr, #284).
• @describeIn with plain functions now correctly includes the function name
  and can be applied to data documentation. (@jimhester, #285, #288).
• Works again when called from Rscript and methods is not loaded
  (@krlmlr, #305).

Roxygen2 4.0.2

• If you don't use @exports or other namespace directives, your namespace
  file will not be touched (#276).
• Methods no longer automatically attempt to inherit parameters from
  their generic. It's too fraught with difficulty (#261).
• Roxygen now understands what to do with setReplaceMethod() (#266).
• Parameter documentation is ordered according to the order of the formals, if
  possible (@krlmlr, #63).
• Export is_s3_method().
• Roxygen no longer fails when run in non-UTF-8 locales on windows.

Roxygen2 4.0.1

• Explicit updateRoxygen() is no longer needed - roxygenize() does the
  right thing the first time it is run.
• Exporting a S4 generic works (#246).
• roxygenise() no longer complains about absense of wrap field because it's
  so unlikely that anyone wants the old behaviour (#245).

roxygen2 4.0.0

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.

Roxygen2 3.1.0

Documentation for reference classes

It's now possible to document reference classes, using the "docstring"
convention described in ?setRefClass. If you want to provide a short
paragraph description of what a method does, make the first component of the
message a string containing the description, e.g.:

setRefClass("A", methods = list(
  f = function(a, b) {
    "Take numbers \code{a} and \code{b} and add them together"
    a + b
  }
))

Unlike the documentation for R functions, the documentation for methods can
be quite succinct.

Roxygen adopts the convention that documented methods are public, and will
be listed in the man page for the object. Undocumented methods are private and
will not be shown in the documentation. The methods for all superclasses are
also listed, so that you don't need to flip through multiple pages of
documentation to understand what you can do with an object. All documented
methods will be placed in a bulleted list in a section titled "Methods", the
method usage will be automatically prepended to the docstring.

Minor fixes and improvements

• Fixes for Rcpp 0.11.0 compatibility.
• roxygenise() now invisible returns a list of all files generated
  by individual roclets. This is useful for tools that want to figure
  out if there are extra files in the man/ directory.
• is_s3_generic() now recognises group generics (#166).
• Don't try and add parameters for data objects (#165).
• Sort output of families using C locale (#171).
• @family now escapes function names in references (#172).

roxygen2 3.0.0

Roxygen2 now fully supports S4 and RC (reference classes) - you should no
longer need to manually add @alias or @usage tags for S4 classes, methods
and generics, or for RC classes.

• The default usage definitions are much better, generating the correct
  usage for data sets (#122), S3 methods (without additional @method tag),
  S4 generics, S4 methods, and for replacement (#119) and infix functions.
  Backslashes in function arguments in are correctly escaped. Usage statements
  also use a more sophisticated line wrapping algorithm so that they should
  cause fewer problems with the R CMD check line limit. (#89, #125).
• S4 classes, S4 methods, and RC classes are given better default topics,
  and the file names corresponding to those topics are shorter.
• S4 methods will automatically inherit parameter documentation from their
  generic.
• @slot name description allows you to document the slots of a S4 class.

S3 support has also been improved: roxygen2 now figures out whether a function
is a S3 method or generic. (In the rare cases it does so incorrectly, use
@method to manually describe the generic and class associated with a method).
This means you can remove existing uses of @method, and can replace
@S3method with @export.

Roxygen now has support for package specific options through the Roxygen
field in the DESCRIPTION. The value of the field should be R code that
results in a list. Currently only wrap and roclet values are supported:

• Turn off Rd re-wrapping with adding Roxygen: list(wrap = FALSE)
• Change the default roclets by specifying
  Roxygen: list(roclets = c("collate", "rd"))

Roxygen 3.0 also includes a number of minor fixes and improvements:

• Infix functions are now escaped correctly in the NAMESPACE. (Thanks to
  @crowding, #111)
• roxygenise() now works more like devtools::document() and only ever works
  in the current directory. The arguments roxygen.dir, overwrite,
  copy.package and unlink.target have been deprecated due to potential
  data loss problems.
• The collate roclet is no longer a roclet: it processes R files using custom
  code (only statically, not dynamically) and is designed to be executed before
  the code is sourced. Run update_collate() to update the Collate directive
  based on @include tags - if there are none present, a collate directive
  will not be generated.
• @useDynLib now works with more possible specifications - if you include a
  comma in the tag value, the output will be passed as is. This means that
  @useDynLib mypackage, .registration = TRUE will now generate
  useDynLib(mypackage, .registration = TRUE) in the NAMESPACE. (#124)
• inst directory not created by default (#56).
• Explicitly depend on utils and methods packages to make roxygen
  compatible with Rscript (#72). Import digest package instead of
  depending on it.
• Always use C locale when sorting NAMESPACE file or tags in .Rd files.
  This ensures a consistent ordering across systems (#127).
• Templates with extension .r are supported on case-sensitive file systems
  (#115). Template variables now actually work (#160, thanks to @bronaugh).
• Suppress default aliases, format and usage with @aliases NULL,
  @format NULL and @usage NULL.