Skip to content

Releases: r-lib/roxygen2

roxygen2 7.3.2

28 Jun 12:53
Compare
Choose a tag to compare
  • @includeRmd now additionally sets options(cli.hyperlink = FALSE) to make
    code run in included .Rmds even more consistent across sessions (#1620).

roxygen2 7.3.1

22 Jan 22:02
Compare
Choose a tag to compare
  • S3 method export warning no longer fails if class contains { or } (#1575).

  • @family lists are now ordered more carefully, "foo1" comes after "foo"
    (#1563, @krlmlr).

  • @importFrom works again for quoted non-syntactic names, e.g.
    @importFrom magrittr "%>%" or @importFrom rlang `:=`
    (#1570, @MichaelChirico). The unquoted form @importFrom magrittr %>%
    continues to work. Relatedly, @importFrom directives matching no known
    functions (e.g. @importFrom utils plot pdf) produce valid NAMESPACE files
    again.

  • Multi-line @rawNamespace no longer break re-runs of namespace_roclet()
    (#1572, @MichaelChirico).

roxygen2 7.3.0

11 Jan 21:12
Compare
Choose a tag to compare

New features

  • @docType package now works more like documenting "_PACKAGE",
    creating a {packagename}-package alias and clearly suggesting that
    you should switch to "_PACKAGE" instead (#1491).

  • _PACKAGE will no longer generate an alias for your package name if
    a function of the same name exists (#1160).

  • The NAMESPACE roclet now reports if you have S3 methods that are missing
    an @export tag. All S3 methods need to be @exported (which confusingly
    really registers the method) even if the generic is not. This avoids rare,
    but hard to debug, problems (#1175). You can suppress the warning with
    @exportS3Method NULL (#1550).

  • The NAMESPACE roclet once again regenerates imports before loading
    package code and parsing roxygen blocks. This has been the goal for a long
    time (#372), but we accidentally broke it when adding support for code
    execution in markdown blocks. This resolves a family of problems where you
    somehow bork your NAMESPACE and can't easily get out of it because you
    can't re-document the package because your code doesn't reload.

Minor improvements and bug fixes

  • If you document a function from another package it is automatically
    imported. Additionally, if you set @rdname or @name you can opt out
    of the default reexports topic generation and provide your own docs
    (#1408).

  • Generate correct usage for S4 methods with non-syntactic class names.

  • The ROXYGEN_PKG env var provides the name of the package being documented
    (#1517).

  • @describeIn foo now suggests that you might want @rdname instead
    (#1493). It also gives a more informative warning if you use it with an
    unsupported type (#1490).

  • In DESCRIPTION, URLs containing escapes in URL and BugReports are
    now correctly handled (@HenningLorenzen-ext-bayer, #1415). Authors can now
    have multiple email addresses (@jmbarbone, #1487).

  • escape_examples() is now exported (#1450).

  • @exportS3Method provides the needed metadata to generate correct usage
    for S3 methods, just like @method (#1202).

  • is_s3_generic() now ignores non-function objects when looking for a
    candidate function. I believe this is closer to how R operates.

  • @import and friends are now ignored if they try to import from the
    package being documented. This is useful to add self-dependencies in
    standalone files meant to be used in other packages (r-lib/usethis#1853).

  • @importFrom throws a friendlier error if you try and import a non-existing
    functions (@MichaelChirico, #1409).

  • @include now gives an informative warning if you use a path that doesn't
    exist (#1497).

  • @inherit can now also inherit from @format (#1293).

  • @family lists are now ordered more carefully, "foo1" comes after "foo" (#1563, @krlmlr).

roxygen2 7.2.3

10 Dec 18:23
Compare
Choose a tag to compare
  • roxygen2 now supports HTML blocks in markdown. They are only included
    in the HTML manual. They can also be produced as the output of code
    chunks.

  • Improved support for RStudio IDE.

roxygen2 7.2.2

14 Nov 22:29
Compare
Choose a tag to compare
  • @includeRmd calls local_reproducible_output() to make code run in
    included .Rmds more consistent with other sources (#1431).

  • Fix duplicated argument in roxy_block() to avoid CRAN removal.

roxygen2 7.2.1

18 Jul 16:40
Compare
Choose a tag to compare

Tags

  • All built-in tags are now documented so that you can do (e.g.) ?"@param"
    to get a basic description of @param and a pointer where to learn more
    (#1165). This is powered by a new tags_list() lists all tags defined by
    roxygen2 and tags_metadata() provides some useful information about them
    for use by (e.g.) IDEs (#1375).

  • @describeIn can now be used to combine more types of functions
    (generics, methods and other functions) into a single topic.
    The resulting section organises the functions by type (#1181)
    and displays methods like function calls. Methods are recognized only if
    they extend the generic in the destination,or if the destination can
    heuristically be identified as a constructor.

  • Code evaluated in inline markdown code chunks and @eval/@evalRd/
    @evalNamespace is now evaluated in an environment designed to be more
    reproducible and to suppress output that won't work in Rd (e.g. turning
    off colour and unicode support in cli) (#1351). They now also set
    knitr options comment = #> (#1380) and collapse = TRUE (#1376).

  • @export will now export both the class and constructor function when
    applied to expressions like foo <- setClass("foo") (#1216).

  • @includeRmd now gives better feedback when it fails (#1089).

(R)markdown

  • New knitr_chunk_options option (in the Roxygen entry of
    DESCRIPTION or in man/roxygen/meta.R) is added to the knitr chunk
    options that roxygen2 uses for markdown code blocks and inline
    code (#1390).

  • PDF figures are only included the PDF manual, and SVG figures are only
    included in the HTML manual (#1399).

  • You can now use alternative knitr engines in markdown code blocks (#1149).

  • Generated HTML for code blocks never includes "NA" for language (#1251).

  • Using a level 1 heading in the wrong tag now gives a more useful warning
    (#1374).

  • Fix bug interpolating the results of indented inline RMarkdown (#1353).

Other

  • If you have a daily build of RStudio, the lists of changed Rd files are
    now clickable so you can immediately see the rendered development
    documentation (#1354).

  • R6 documentation no longer shows inherited methods if there aren't any
    (#1371), and only links to superclass docs if they're actually available
    (#1236).

  • Automated usage no longer mangles nbsp in default arguments (#1342).

roxygen2 7.2.0

13 May 19:32
Compare
Choose a tag to compare

New features

  • The NAMESPACE roclet now preserves all existing non-import directives during
    it's first pre-processing pass. This eliminates the "NAMESPACE has changed"
    messages and reduces the incidence of namespace borking (#1254).

  • @inheritParams now only inherits exact multiparameter matches, so if you're
    inheriting from a function with @param x,y you'll only get the parameter
    documentation if your function needs docs for both x and y (#950).

  • All warning messages have been reviewed to be more informative and
    actionable (#1317). @title now checks for multiple paragraphs.
    @export gives a more informative warning if it contains too many lines.
    (#1074). All tags warn now if only provide whitespace (#1228), and
    problems with the first tag in each block are reported with the correct line
    number (#1235).

  • If you have a daily build of RStudio, roxygen2 warnings will now include a
    clickable hyperlink that will take you directly to the problem (#1323).
    This technology is under active development across the IDE and the cli
    package but is extremely exciting.

Minor improvements and bug fixes

  • roxygen2 can once again read UTF-8 paths on windows (#1277).

  • @authors are de-duplicated in merged documentation (@DanChaltiel, #1333).

  • @exportS3method pkg::generic now works when pkg::generic isn't
    imported by your package (#1085).

  • @includeRmd is now adapted to change in rmarkdown 2.12 regarding math
    support in github_document() (#1304).

  • @inherit and friends perform less aggressive link tweaking, eliminating
    many spurious warnings. Additionally, when you do get a warning, you'll
    now always learn which topic it's coming from (#1135). Inherited
    \ifelse{}{}{} tags are now inserted correctly (without additional {})
    (#1062).

  • @inhert now supports inheriting "Notes" with @inherit pkg::fun note
    (@pat-s, #1218)

  • Automatic @usage now correctly wraps arguments containing syntactically
    significant whitespace (e.g anonymous functions) (#1281) and non-syntactic
    values surrounded by backticks (#1257).

  • Markdown:

    • Code blocks are always wrapped in <div class="sourceCode">
      even if the language is unknown (#1234).

    • Links with markup (e.g. [foo `bar`][target]) now cause an informative
      warning instead of generating invalid Rd.

    • Curly braces in links are now escaped (#1259).

    • Inline R code is now powered by knitr. Where available, (knit) print
      methods are applied (#1179). This change alters outputs and brings roxygen
      in line with console and R markdown behavior. x <- "foo" no longer
      inserts anything into the resulting documentation, but x <- "foo"; x
      will.

  • roxygen2 no longer generates invalid HTML (#1290).

  • DOIs, arXiv links, and urls in the Description field of the DESCRIPTION
    are now converted to the appropriate Rd markup (@dieghernan, #1265, #1164).
    DOIs in the URL field of the DESCRIPTION are now converted to Rd's
    special \doi{} tag (@ThierryO, #1296).

roxygen2 7.1.2

08 Sep 11:54
Compare
Choose a tag to compare
  • The new @examplesIf tag can be used to create conditional
    examples. These examples only run if a specified condition
    holds (#962).

  • roxygen2 is now licensed as MIT (#1163).

  • Bug fix for upcoming stringr 2.0.0 release.

  • Code blocks with language now add sourceCode to the generated div; this
    makes syntax highlighting more consistent across downlit/pandoc/knitr/roxygen2.

  • Percent signs in markdown link targets, e.g. [text](https://foo/ba%20r)
    are now handled correctly (#1209).

roxygen2 7.1.1

29 Jun 12:09
Compare
Choose a tag to compare
  • When processing cross package markdown links (e.g. [pkg::fun()]),
    roxygen2 now looks up the file it needs to link to, instead of linking to
    the topic, to avoid "Non-file package-anchored links" R CMD check warnings.

  • R6 methods and re-exported functions are always sorted in the C locale;
    this ensures they're always sorted the same way in every environment (#1077).

  • roxygen2 now supports inline markdown code and code chunks inside
    Rd tags. In particular in \out{} (#1115).

roxygen2 7.1.0

11 Mar 18:44
Compare
Choose a tag to compare

New features

  • roxygen2 now supports inline markdown code and also code chunks,
    using the same notation as the knitr package. For example:

    #' This manual was generated at: `r Sys.time()`. 
    #' ... 
    #' `mtcars` is a data frame with `r ncol(mtcars)` columns, here 
    #' is a summary of them: 
    #' 
    #' ```{r} 
    #' summary(mtcars) 
    #' ``` 

    See vignette("rd-formatting") for details.

  • roxygen2 now keeps using Windows (CR LF) line endings for files that
    already have CR LF line endings, and uses LF for new files (#989).

Minor improvements and bug fixes

  • Auto-generated package documentation can now handle author ORCID comments
    containing full url (#1040).

  • Hyperlinks to R6 methods are also added in the PDF manual (#1006).

  • Empty annotations (alternate text) for figures added via markdown are now
    omitted. This caused issues when generating pkgdown web sites (#1051).

  • Roxygen metadata can now have a packages element, giving a character vector
    of package names to load. This makes it easier to use extension package that
    provide new tags for existing roclets (#1013). See ?load_options for
    more details.

    Roxygen: list(markdown = TRUE, packages = "roxygenlabs") 
  • @evalNamespace() works again (#1022).

  • @description NULL and @details NULL no longer fail; instead, these tags
    are ignored, except for @description NULL in package level documentation,
    where it can be used to suppress the auto-generated Description section
    (#1008).

  • Multiple @format tags are now combined (#1015).

  • The warning for @section titles spanning multiple lines now includes a
    hint that you're missing a colon (@maelle, #994).

  • Can now document objects created with delayedAssign() by forcing
    evaluation at documentation time (#1041)