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.