roxygen2 6.1.0

  2018/08/07

  r-lib, roxygen2

  Mara Averick

We’re delighted to announce that roxygen2 6.1.0 is now on CRAN. The goal of roxygen is to make documenting your code as easy as possible. It allows you to describe your functions in comments next to their definitions, and processes your source code and comments to produce .Rd files in the man/ directory, as well as. roxygen will also create a NAMESPACE for you, and will manage the Collate field in DESCRIPTION.

This release includes several updates to markdown parsing, as well as some new features we highlight below. For a full list of updates and changes, please see the release notes.

New features

The NAMESPACE roclet now works in two passes - it first generates the NAMESPACE containing only import directives because 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 editing the NAMESPACE by hand.

roxygenise() now uses pkgload::load_all() instead of a homegrown solution to simulate package loading. This is one of the benefits of the conscious uncoupling of devtools. The simulated package loading is needed because roxygen2 uses run-time information to generate the documentation. This should reduce S4-related problems, and ensure that devtools::document() and roxygenise() always have the same behaviour.

@evalRd foo() evaluates foo() defined in the package namespace and inserts the results into the current block. The code should return a character vector with one entry for each line (and they should not start with #'). This provides a flexible way to extract out duplicated documentation. For example:

today <- function() {
  paste0("Today is \\strong{", format(Sys.Date(), "%A"), "}")
}

#' @evalRd today()
NULL

today() will be executed every time that you run roxygen2. There are two small limitations to the current implementation: the generated roxygen will not affect the @md/@noMd status, and @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.

Improvements to markdown parsing

Starting from version 6.0.0, roxygen supports markdown markup within most roxygen tags (learn more here). You can switch to markdown documentation with usethis::use_roxygen_md(), which uses the roxygen2md package to convert Rd expressions to markdown.

In this version, we’ve made a number of bug fixes to markdown translation:

  • Whitespace between words in link text is now preserved as single space for links of the form [text][fcn] and [text](URL).

  • Code in link text is now properly rendered as code.

  • The parsing of markdown links has been modified to reduce false positives. If you still get a false positive, you can add \\ in front of the [ to avoid its being converted to a link.

  • Markdown features that are not supported should now generate a warning identifying them as such.

Acknowledgements

Thank you to the 114 people who have contributed to this release: ＠agwells, ＠alexpghayes, ＠apomatix, ＠Ax3man, ＠BarkleyBG, ＠BillWeld, ＠brodieG, ＠brry, ＠bwiernik, ＠cfhammill, ＠coatless, ＠coldfir3, ＠ColinFay, ＠ctbrown, ＠danielsjf, ＠dankelley, ＠dewittpe, ＠dongzhuoer, ＠dpritchLibre, ＠ebridge2, ＠egnha, ＠evanbiederstedt, ＠fangly, ＠FelixErnst, ＠flyeye, ＠flying-sheep, ＠graemeleehickey, ＠grst, ＠gvegayon, ＠hadley, ＠HenrikBengtsson, ＠hughjonesd, ＠ijlyttle, ＠inkrement, ＠jackwasey, ＠Jakob2014uafmx, ＠jcrodriguez1989, ＠jeis2497052, ＠jennybc, ＠jimhester, ＠jkl789, ＠joethorley, ＠JoFAM, ＠JohnMount, ＠jonlehrer, ＠JoshOBrien, ＠jpfrench81, ＠jpritikin, ＠jrosen48, ＠karawoo, ＠kbenoit, ＠kevinushey, ＠klmr, ＠krivit, ＠krlmlr, ＠leifeld, ＠levisc8, ＠lindbrook, ＠lionel-, ＠lorenzwalthert, ＠Lucaweihs, ＠maelle, ＠MansMeg, ＠martin-mfg, ＠mashranga, ＠maxheld83, ＠mb706, ＠mcol, ＠md0u80c9, ＠mikmart, ＠mixtrak, ＠mkoohafkan, ＠mvkorpel, ＠natgoodman, ＠nteetor, ＠nuno-agostinho, ＠PeterVermont, ＠philmikejones, ＠pierreroudier, ＠pkq, ＠privefl, ＠publicus, ＠QuLogic, ＠r2evans, ＠rabutler, ＠renozao, ＠richierocks, ＠romainfrancois, ＠rvlenth, ＠s-fleck, ＠saralinker, ＠sgibb, ＠spluque, ＠ssdavenport, ＠ssokolen, ＠Stanwood18, ＠statnmap, ＠stufield, ＠StuHorsman, ＠sylvainschmitt, ＠sz-cgt, ＠tbates, ＠teo029, ＠tpbilton, ＠twang2218, ＠ugroempi, ＠unDocUMeantIt, ＠vjcitn, ＠WastlM, ＠xhdong-umd, ＠xhudik, ＠ximeg, ＠yannickspill, and ＠yutannihilation.

Contents