Movatterモバイル変換

roxytypes

Typed parameter definitionroxygen2 tag

Quick Start

Convert your package

If you already have a codebase and you’d like to convert it to useroxytypes, you can use:

roxytypes::convert()

You’ll be prompted with a preview of changes and the option tocontinue by making edits or aborting changes. By default, will look fortype signatures as parenthesized inline code at the start of yourdescriptions. That is, that descriptions are written like(`type`) description.

If that’s not the case, you can specify your own format. For example,if your types were in square brackets, you could specify a formatlike:

roxytypes::convert(format ="[`{type}`] {description}")

By default, conversions will only happen if an existing type is foundusing the provided type format. If you’d like to convert all possibletags, passunmatched = TRUE. However new typed tags willonly be partially populated and will produce documentation notes untilthey are filled in.

Tags from scratch

Use the@typed tag to define parameters, replacing the@param tag.

The@typed tag expects input in the form:

#' @typed <var>: <type>#'   <description>

The newline after thetype field is a meaningfuldelimiter to avoid having to disambiguate between type annotations andwritten descriptions. In practice it looks something like this:

#' Example#'#' @typed who: character#'   Who you'd like to say hello to.#'#' @typedreturn: NULL#'   `cat` output returned.#'hello<-function(who ="World") {cat("Hello, ", who,"!\n",sep ="")}

Next order of business is to install the package and declare theroxygen2 dependency.

DESCRIPTION

Config/Needs/documentation:    roxytypesRoxygen:    list(markdown = TRUE, packages = "roxytypes")

With all of that set up, the only thing left is to rebuild yourdocs!

Configuration

roxytypes accepts a number of configuration fields. Fordefaults, see?config.

Formatting

The style of documentation can be configured usingConfig/roxytypes:

DESCRIPTION

Config/roxytypes: list(format = "(`{type}`): {description}")

The format string usesglue and can be expected to havefieldsname,type anddescription. The parameter name will always be the namedargument value, but may be reused for parts of the description.

Altenatively, you can provide a function that accepts the parsedroxygen2 tag and the fields as named arguments.

For more advanced formatting, see?tags or?typed.

roxylintcompatible

@typed tags come with their ownroxylintlinters. To benefit from linting of@typed tags, simply addtheroxylint::roxylint roclet.

DESCRIPTION

Roxygen:  list(    markdown = TRUE,    packages = c("roxylint", "roxytypes"),    roclets = c("namespace", "rd", "roxylint::roxylint")  )

tip!

If yourRoxygen section gets too long, you can also putthis content inman/roxygen/meta.R where you can benefitfrom all the perks of your editor’s R file handling.