roxygen2 7.0.2

• \example{} escaping has been improved (again!) so that special escapes
  within strings are correctly escaped (#990).

roxygen2 7.0.1

• @includeRmd has now an optional second argument, the top level section
  the included file will go to. It defaults to the details section (#970).
  Code chunks are now evaluated in a child of the global environment (#972).

• @inheritParams does a better job of munging links.

  Links of the form \link[=topic]{text} are now automatically converted to
  \link[pkg:topic]{text} when inherited from other packages (#979).

  Internal has_topic() helper has a better implementation; this means that
  links should no longer be munged unnecessarily (#973).

• \example{} escaping has been considerably simplified (#967), and is now
  documented in escape_example().

• In \usage{}, S3/S4 methods are no longer double-escaped (#976).

• Markdown tables with cells that contain multiple elements (e.g. text and code)
  are now rendered correctly (#985).

• Markdown code blocks containing operators and other special syntax
  (e.g. function, if, +) now converted to \code{} not \verb{} (#971).

roxygen2 7.0.0

New features

New tags

• @includeRmd {path.Rmd} converts an .Rmd/.md file to .Rd and includes
  it in the manual page. This allows sharing text between vignettes,
  README.Rmd, and the documentation. See vignette("rd") for details (#902).

• @order {n} tag controls the order in which blocks are processed. You can
  use it to override the usual ordering which proceeds from the top of
  each file to the bottom. @order 1 will be processed before @order 2,
  and before any blocks that don't have an explicit order set (#863).

• @exportS3Method tag allows you to generate S3method() namespace
  directives (note the different in capitalisation) (#796). Its primary use is
  for "delayed" method registration, which allows you to define methods for
  generics found in suggested packages (available in R 3.6 and greater).
  For example,

  #' @exportS3Method package::generic 
  generic.foo <- function(x, ...) { 
   
  } 

  will generate

  S3method(package::generic, foo) 
  

  (See vctrs::s3_register()
  you need a version that works for earlier versions of R).

  It also has a two argument form allows you generate arbitrary S3method()
  directives:

  #' @exportS3Method generic class 
  NULL 

  S3method(generic, class) 
  

• New @returns is an alias for @return (#952).

R6

roxygen2 can now document R6 classes (#922). See vignette("rd") for details.

Markdown improvements

• Rd comments (%) are now automatically escaped. You will need to replace any
  existing uses of \% with % (#879).

• Markdown headings are supported in tags like @description, @details,
  and @return (#907, #908). Level 1 headings create a new top-level
  \section{}. Level 2 headings and below create nested \subsections{}.

• Markdown tables are converted to a \tabular{} macro (#290). roxygen2
  supports the GFM table syntax
  which looks like this:

  | foo | bar | 
  | --- | --- | 
  | baz | bim | 

• Markdown code (`foofy`) is converted to to either \code{} or
  \verb{}, depending on whether it not it parses as R code. This better
  matches the description of \code{} and \verb{} macros, solves a certain
  class of escaping problems, and should make it easier to include arbitrary
  "code" snippets in documentation without causing Rd failures (#654).

• Markdown links can now contain formatting, e.g. [*mean*][mean] will now
  generate \link[=mean]{\emph{mean}}.

• Use of unsupported markdown features (e.g. blockquotes, inline HTML,
  and horizontal rules) generates informative error messages (#804).

Default usage

• The default formatting for function usage that spans multiple lines has
  now changed. Previously, the usage was wrapped to produce the smallest number
  of lines, e.g.:

  parse_package(path = ".", env = env_package(path),  
    registry = default_tags(), global_options = list()) 

  Now it is wrapped so that each argument gets its own line (#820):

  parse_package( 
    path = ".", 
    env = env_package(path), 
    registry = default_tags(), 
    global_options = list() 
  ) 

  If you prefer the old behaviour you can put the following in your
  DESCRIPTION:

  Roxygen: list(old_usage = TRUE) 
  

Code loading

roxygen2 now provides three strategies for loading your code (#822):

• load_pkgload(), the default, uses pkgload.
  Compared to the previous release, this now automatically recompiles your
  package if needed.

• load_source() attaches required packages and source()s all files in R/.
  This is a cruder simulation of package loading than pkgload (and e.g. is
  unreliable if you use S4 extensively), but it does not require that the
  package be compiled. Use if the default strategy (used in roxygen2 6.1.0
  and above) causes you grief.

• load_installed() assumes you have installed the package. This is best
  used as part of a bigger automated workflow.

You can override the default either by calling (e.g.) roxygenise(load_code = "source")) or by setting the load option in your DESCRIPTION: Roxygen: list(load = "source").

Options

• As well as storing roxygen options in the Roxygen field of the
  DESCRIPTION you can now also store them in man/roxygen/meta.R (#889).
  The evaluation of this file should produce a named list that maps option
  names to values.

• roxygen now also looks for templates in man/roxygen/templates (#888).

• New rd_family_title option: this should be a named list, and is used to
  overrides the default "Other family: " prefix that @family generates.
  For example, to override the prefix generated by @family foo place
  rd_family_title <- list(foo = "Custom prefix: ") in
  man/roxygen/meta.R (#830, @kevinushey).

Breaking changes

• Rd comments (%) are automatically escaped in markdown formatted text.
  This is a backward incompatible change because you will need to replace
  existing uses of \% with % (#879).

• Using @docType package no longer automatically adds -name. Instead
  document _PACKAGE to get all the defaults for package documentation, or
  use @name to override the default file name.

• @S3method has been removed. It was deprecated in roxygen2 4.0.0
  released 2014-05-02, over 5 years ago.

• Using the old wrap option will now trigger a warning, as hasn't worked
  for quite some time. Supress the error by deleting the option from your
  DESCRIPTION.

Extending roxygen2

The process for extending roxygen2 with new tags and new roclets has been completely overhauled, and is now documented in vignette("extending"). If you're one of the few people who have written a roxygen2 extension, this will break your code - but the documentation, object structure, and print methods are now so much better that I hope it's not too annoying! Because this interface is now documented, it will not change in the future without warning and a deprecation cycle.

If you have previously made a new roclet, the major changes are:

• The previously internal data structures used to represent blocks and tags
  have been overhauled. They are now documented and stable. See roxy_block()
  and roxy_tag() for details.

• roclet_tags() is no longer used; instead define a roxy_tag_parse() method.
  For example, if you create a new @mytag tag, it will generate a class of
  roxy_tag_mytag, and will be parsed by roxy_tag_parse.roxy_tag_mytag()
  method. The method should return a new roxy_tag() object with the
  val field set.

  This means that the registry argument is no longer needed and has
  been removed.

• rd_section() and roxy_tag_rd() are now exported so that you can more
  easily extend rd_roclet() with your own tags that generate output in
  .Rd files.

• global_options is no longer passed to all roclet methods. Instead, use
  roxy_meta_get() to retrieve values stored in the options (#918).

• tag_two_part() and tag_words() are now simple functions, not function
  factories.

• tag_markdown_restricted() has been removed because it did exactly the
  same thing as tag_markdown().

A big thanks goes to @mikldk for starting on the vignette and motivating me to make the extension process much more pleasant (#882).

Bug fixes and minor improvements

• Empty roxygen2 lines at the start of a block are now silently removed (#710).

• Whitespace is automatically trimmed off the RoxygenNote field when
  comparing the installed version of roxygen2 to the version used to
  generate the documentation (#802).

• Files generated on Windows systems now retain their existing line endings, or
  use unix-style line endings for new files (@jonthegeek, @jimhester, #840).

• roxygen2 now recognises fully qualified S4 functions like
  methods::setGeneric(), methods::setClass() and methods::setMethod()
  (#880).

• Package documentation now converts ORCIDs into a useful link (#721).
  The package logo (if found at man/images/logo.png) is now scaled to 120px
  wide (@peterdesmet, #834).

• Documenting an S4 method that has a .local() wrapper no longer fails with
  an obscure error message (#847).

• Functions documented in reexports are now sorted alphabetically by
  package (#765).

• @describeIn can now be used with any combination of function types
  (#666, #848).

• @description and @detail tags are automatically generated from the
  leading description block, and now have correct line numbers (#917).

• @example and @examples are interwoven in the order in which they
  appear (#868).

• In @examples, escaped ' and " in strings are no longer doubly escaped
  (#873).

• @family automatically adds () when linking to functions (#815),
  and print each link on its own line (to improve diffs).

• When @inheriting from external documentation, \link{foo} links
  are automatically transformed to \link{package}{foo} so that they work in
  the generated documentation (#635). \href{} links in external inherited are
  now inserted correctly (without additional {}) (#778).

• @inheriting a a function with no argum...

roxygen2 6.1.1

• Now specifically imports recent version of desc package (>= 1.2.0) to
  fix various parsing issues (@crsh, #773, #777, #779). Multi-line DESCRIPTION
  collate directives now correctly parsed on windows (@brodieG, #790).

• roxygenise() no longer recompiles packages containing src code (#784).

• roxygenise() now stops with an informative error message when run in a
  directory that's not the package root (@mikmart, #704).

roxygen2 6.1.0

New features

• The NAMESPACE roclet nows works in two passes - it first generates the
  a NAMESPACE containing only import directives becaues this can be generated
  without evaluating the code in the package. This alleviates a problem
  where it was previously possible to get into a state that you could only
  get out of by carefully editting the NAMESPACE by hand (#372).

• @evalRd foo() evaluates foo() defined in the package namespace and inserts
  the results into the current block (#645). The code should return a character
  vector with one entry for each line (and they should not start with #').

  There are two small limitations to the current implementation:

  1. The generated roxygen will not affect the @md/@noMd status
  2. @evalRd does not work inside templates.

• @evalNamespace does for NAMESPACE what @evalRd does for Rd files:
  you give it R code that produces a literal entry in NAMESPACE when
  run. This should make it easier to export functions that are generated by
  other functions in your package (#531, @egnha).

• @inherits can now inherit examples (#588).

• vignette("rd") received a thorough updating for current best-practices.
  The vignette still needs more work so pull requests are greatly appreciated
  (#650).

• roxygenise() uses pkgload::load_all() instead of a home grown solution
  to simulate package loading (this is needed because roxygen2 uses run-time
  information to generate the documetation). This should reduce S4 related
  problems and ensures that devtools::document() and roxygenise() always
  have exactly the same behaviour (#568, #595).

• If an inherited section cannot be found, the warning contains the help
  page from which that section was requested (#732, @krlmlr).

• roxygen2 now always reads and writes using UTF-8 encoding. If used with a
  package that does not have Encoding: UTF-8 in the DESCRIPTION, you'll
  now get a warning (#564, #592).

Extension API

• Roxygen blocks now have an official structure as encoded in
  roxy_block(). It is a named list containing the tags with attributes
  providing other metadata.

• The parsed argument to roclet_process() have been replaced with
  separate blocks and env arguments.

• New roclet_preprocess() generic makes it possible for roclets to perform
  actions before code is evaluated.

• parse_package(), parse_file() and parse_code() provide an exported API
  that allows you to use roxygen's parsing code independently of creating
  roclets.

Minor improvements and bug fixes

• All tags (including @alias) are now de-duplicated and consistently sorted.
  This reduces spurious diffs (#586, @flying-sheep).

• @concept now generates one \concept per tag (#611).

• The default @description (i.e. the title) is now added much later in the
  process. That means that @inherit description now works when you have
  specified a title for the inheritor (#629) and the default description
  is slightly nicer when merging multiple blocks.

• @family automatically adds its value to concepts (#611).

• @inherits: The mechanism for extracting inherited Rd does a better job of
  preserving escapes (#624)

• Empty .Rbuildignore now handled correctly (#576).

• Stricter regular expression ensures only files ending with .R or .r are
  parsed for roxygen comments (#625).

• Objects with names starting with a dot are now by default documented in
  files with prefix 'dot-'.

• Roclets can now access global options as designed. This allows templates to
  use markdown formatting if set globally (#594).

• You can now autogenerate package documentation even if you don't have
  Authors@R (#606).

• Multiple given and/or family names are now supported in the
  Authors@R field of the DESCRIPTION file (#672, @sgibb).

• If a package logo exists (man/figures/logo.png) it will be automatically
  included in generated package docs (#609).

• Usage for data objects now correctly generated, avoiding double escaping
  other components of usage (#562).

• Improvements to markdown translation:

  • Code in link text is now properly rendered as code (#620, @egnha).

  • Whitespace between words in link text is now preserved as single
    space for links of the form [text][fcn] and [text](URL)
    (#628, #754, #760, @egnha and @jennybc).

  • % in inline code (#640), code blocks (@nteetor, #699) and
    links (#724) is now automatically escaped.

  • Parsing of markdown links has been tweaked to reduce false positives
    (#555). If you still get a false positive, you can now put \\ in front
    of the [ to avoid it being converted to a link (#720). Links can no
    longer be followed by { to avoid spurious matches to Rd commands like
    \Sexpr{}.

  • Unsupported markdown features now generate a mildly helpful warning
    instead of throwing an utterly useless error (#560).

• person() now supports all
  MARC Relator role codes
  (#662, @Publicus).

• topic_add_usage() now outputs formatted "Usage" section with max
  width of 80 characters thanks to a now more flexible wrap_string()
  (@JoshOBrien, #719).

roxygen2 6.0.1

• Allowing empty lines in .Rbuildignore. Previously, empty lines caused all
  files to be ignored. (#572, @jakob-r)
• Automatically generating a usage section for an infix function containing "<-"
  no longer removes "<-" from the function name (#554).

roxygen2 6.0.0

Markdown

• Most fields can now be written using Markdown markup instead of the
  traditional Rd language. You can turn on Markdown globally by adding
  Roxygen: list(markdown = TRUE) to DESCRIPTION. The @md / @noMd
  tags turn Markdown parsing on / off for the given block. See
  vignette("markdown") for more details (#364, #431, #499, #506, #507),
  by @gaborcsardi

Improved inheritance

• New @inheritDocParams allows you to automatically generate parameter
  documentation for ... for the common case where you pass ... on to
  another function (#512). Because you often override some arguments, it
  comes with a flexible specification for argument selection:

  • @inheritDotParams foo takes all parameters from foo()

  • @inheritDotParams foo a b e:h takes parameters a, b, and all
    parameters between e and h

  • @inheritDotParams foo -x -y takes all parameters except for x and y.

    The documentation generated is similar to the style used in ?plot
    and will eventually be incorporated in to RStudio's autocomplete.

• New @inherit generalises @inheritParams, and allows to you inherit
  parameters, return, references, title, description, details, sections, and
  seealso. The default @inherit my_fun will inherit all, you can document
  an object entirely by specifying only the @inherit tag. Alternatively,
  you can select specific tags to inherit with @inherit my_fun return params
  (#384).
• New @inheritSection fun title allows you to inherit the contents of
  a single section from another topic (#513).
• @inheritParams now works recursively, so that you can inherit parameters
  from a function that inherited its paramters from somewhere else. It
  also better handles \dots as an alias for ... (#504).

Minor improvements and bug fixes

Tags

• @aliases are no longer sorted alphabetically, but instead match the
  order of their usage. This gives you more control in pkgdown.
• @describeIn now escapes special characters in function names (#450).
• @family see alsos are added in the same order they appear, not
  alphabetically (#315). Fixed an issue where .s were sometimes added
  between words within a @family tag (#477, @kevinushey).
• @author is rendered after @seealso.
• @example gives a nice warning message if you accidentally use it instead
  of @examples (#494). Multiple @examples sections are merged (#472, @krlmlr).
• Roxygen will no longer write out topics that don't have a name or title,
  and will instead generate a warning. This makes it easier to detect if
  you've accidentally used @rdname with an incorrect value (#474).

S3

• Non-primitive, internal S3 generics (e.g. 'rbind', 'cbind') are now properly
  detected as S3 generics. (#488, @kevinushey)
• Ensure that functions with S3 class are still treated as functions (#455).
• S3 method declarations via R.methodS3::setMethodS3() and function
  declarations via R.oo::setConstructorS3() are now supported
  (@HenrikBengtsson, #525).

S4

• You can now document setClassUnion()s (#514).
• The default alias for S4 method now re-addeds trailing ANY signatures
  that are sometimes dropped (#460).
• Back references are now wrapped over multiple lines, if long
  (#493, @LiNk-NY).

Other

• "_PACKAGE" documentation now generates a default @seealso combining
  the URL and BugReport fields, and a default @author field generated
  from the Authors@R field (#527). It now works from roxygenise(); before
  it only worked from devtools::document() (#439, @krlmlr).
• Manually created NAMESPACE or documentation files are never overwritten,
  even if using roxygen2 for the first time (@krlmlr, #436).
• Changes to DESCRIPTION (i.e. Collate: and RoxygenNote) now use
  the desc package. This will minimise spurious changes (#430).
• default_data_format() has been renamed to object_format().
• New roclet_find() provides a more flexible way to specify roclets:
  as roclet name (e.g. "rd_roclet"), in an package ("foo::roclet_bar"),
  or with options ("foo::roclet_bar(baz = TRUE)").
• The usage of replacement functions uses non-breaking spaces so that <-
  will never get put on its own line (#484).
• Roxygen now parses nonASCII documentation correctly (as long as UTF-8
  encoded or specified Encoding in DESCRIPTION) (#532, @shrektan),
  and ignores files listed in .Rbuildignore (#446, @fmichonneau).

Extending roxygen2

• Deprecated register.preref.parser() and register.preref.parsers()
  have been removed. register_tags() has also been removed in favour of
  a new roclet_tags() generic.
• roclet() (the constructor), roclet_tags(), roclet_process()
roclet_output(), roc_clean() and now exported making it possible
  to create roclets in other packages. Helper functions roxy_tag() and
  roxy_tag_warning() are also exported.
• new_roclet() is no longer exported - use roclet() instead.

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