Title:	In-Line Documentation for R
Version:	7.3.2
Description:	Generate your Rd documentation, 'NAMESPACE' file, and collation field using specially formatted comments. Writing documentation in-line with code makes it easier to keep your documentation up-to-date as your requirements change. 'roxygen2' is inspired by the 'Doxygen' system for C++.
License:	MIT + file LICENSE
URL:	https://roxygen2.r-lib.org/, https://github.com/r-lib/roxygen2
BugReports:	https://github.com/r-lib/roxygen2/issues
Depends:	R (≥ 3.6)
Imports:	brew, cli (≥ 3.3.0), commonmark, desc (≥ 1.2.0), knitr, methods, pkgload (≥ 1.0.2), purrr (≥ 1.0.0), R6 (≥ 2.1.2), rlang (≥ 1.0.6), stringi, stringr (≥ 1.0.0), utils, withr, xml2
Suggests:	covr, R.methodsS3, R.oo, rmarkdown (≥ 2.16), testthat (≥ 3.1.2), yaml
LinkingTo:	cpp11
VignetteBuilder:	knitr
Config/Needs/development:	testthat
Config/Needs/website:	tidyverse/tidytemplate
Config/testthat/edition:	3
Config/testthat/parallel:	TRUE
Encoding:	UTF-8
Language:	en-GB
RoxygenNote:	7.3.1.9000
NeedsCompilation:	yes
Packaged:	2024-06-27 21:29:24 UTC; hadleywickham
Author:	Hadley Wickham [aut, cre, cph], Peter Danenberg [aut, cph], Gábor Csárdi [aut], Manuel Eugster [aut, cph], Posit Software, PBC [cph, fnd]
Maintainer:	Hadley Wickham <hadley@posit.co>
Repository:	CRAN
Date/Publication:	2024-06-28 08:20:02 UTC

roxygen2: In-Line Documentation for R

Description

Generate your Rd documentation, 'NAMESPACE' file, and collation field using specially formatted comments. Writing documentation in-line with code makes it easier to keep your documentation up-to-date as your requirements change. 'roxygen2' is inspired by the 'Doxygen' system for C++.

Author(s)

Maintainer: Hadley Wickham hadley@posit.co (ORCID) [copyright holder]

Authors:

• Peter Danenberg pcd@roxygen.org [copyright holder]

• Gábor Csárdi csardi.gabor@gmail.com

• Manuel Eugster [copyright holder]

Other contributors:

• Posit Software, PBC [copyright holder, funder]

See Also

Useful links:

• https://roxygen2.r-lib.org/

• https://github.com/r-lib/roxygen2

• Report bugs at https://github.com/r-lib/roxygen2/issues

Check markdown escaping

Description

This is a regression test for Markdown escaping.

Usage

double_escape_md(text)

Arguments

Details

Each of the following bullets should look the same when rendered:

• Backticks: ⁠\⁠, ⁠\%⁠, ⁠\$⁠, ⁠\_⁠

• ⁠\verb{}⁠: ⁠\⁠, ⁠\%⁠, ⁠\$⁠, ⁠\_⁠

[ this isn't a link ] \[ neither is this \]

Value

Double-escaped text.

Examples

"%" # percent
"\"" # double quote
'\'' # single quote

Escape examples

Description

This documentation topic is used primarily for testing and to record our understanding of the ⁠\example{}⁠ escaping rules. See https://developer.r-project.org/parseRd.pdf for the details provided by R core.

Usage

escape_examples(x)

Examples

# In examples we automatically escape Rd comments (%):
100 %% 30
# even if they are in strings
"50%"

# and \ and \v inside of strings and symbols
"\v" # vertical tab
"\\"
# but not comments: \l \v

# other string escapes are left as is
"\""
"\n"

# Otherwise, backslashes and parentheses are left as is. This
# means that you need to escape unbalanced parentheses, which typically only
# occur in \dontshow{}:

print("Hello")


# You also need to escape backslashes in infix operators and comments
# (this is generally rare)
`%\\%` <- function(x, y) x + y
10 %\% 20
# \\ (renders as two backslashes)

Escape Rd markup, to avoid interpreting it as markdown

Description

This is needed, if we want to stay compatible with existing markup, even if markdown mode is switched on. Fragile Rd tags (tags that may contain markup that can be picked up by the markdown parser), are replaced by placeholders. After the markdown to Rd conversion is done, the original text is put back in place of the placeholders.

It puts back the protected fragile Rd commands into the text after the markdown parsing.

Usage

escape_rd_for_md(text)

unescape_rd_for_md(rd_text, esc_text)

Arguments

Details

The list of protected Rd tags is in escaped_for_md.

Some Rd macros are treated specially:

• For if, markdown is only allowed in the second argument.

• For ifelse markdown is allowed in the second and third arguments.

See also roclet-rd.R for the list of tags that uses the markdown-enabled parser. Some tags, e.g. ⁠@aliases⁠, ⁠@backref⁠, etc. only use the standard Roxygen parser.

Value

For escape_rd_for_md: A “safe” version of the input text, where each fragile Rd tag is replaced by a placeholder. The original text is added as an attribute for each placeholder.

For unescape_rd_for_md: Rd text.

Determine if a function is an S3 generic or S3 method.

Description

is_s3_generic compares name to .knownS3Generics and .S3PrimitiveGenerics, then looks at the function body to see if it calls UseMethod().

is_s3_method builds names of all possible generics for that function and then checks if any of them actually is a generic.

Usage

is_s3_generic(name, env = parent.frame())

is_s3_method(name, env = parent.frame())

Arguments

Load package code

Description

roxygen2 is a dynamic documentation system, which means it works with the objects inside your package, not just the source code used to create them. These functions offer various ways of loading your package to suit various constraints:

• load_pkgload() uses pkgload::load_all() to simulate package loading as closely as we know how. It offers high fidelity handling of code that uses S4, but requires that the package be compiled.

• load_source() simulates package loading by attaching packages listed in Depends and Imports, then sources all files in the ⁠R/⁠ directory. This was the default strategy used in roxygen2 6.0.0 and earlier; it's primary advantage is that it does not need compilation.

• load_installed() uses the installed version of the package. Use this strategy if you have installed a development version of the package already. This is the highest fidelity strategy, but requires work outside of roxygen2.

You can change the default strategy for your function with roxygen2 load option. Override the default off pkgload to use the source or installed strategies:

Roxygen: list(load = "source")

Usage

load_pkgload(path)

load_installed(path)

load_source(path)

Arguments

Load roxygen2 options

Description

Options can be stored in the Roxygen field of the DESCRIPTION, or in man/roxygen/meta.R. In either case, the code is parsed and evaluated in a child of the base environment. Call roxy_meta_get() to access current option values from within tag and roclet methods.

Options in man/roxygen/meta.R override those present in DESCRIPTION.

Usage

load_options(base_path = ".")

roxy_meta_get(key = NULL, default = NULL)

Arguments

Possible options

• roclets ⁠<character>⁠: giving names of roclets to run. See roclet_find() for details.

• packages ⁠<character>⁠: packages to load that implement new tags.

• load ⁠<string>⁠: how to load R code. See load for details.

• old_usage ⁠<flag>⁠: use old style usage formatting?

• markdown ⁠<flag>⁠: translate markdown syntax to Rd?

• r6 ⁠<flag>⁠: document R6 classes?

• current_package ⁠<string>⁠ (read only): name of package being documented.

• rd_family_title ⁠<list>⁠: overrides for ⁠@family⁠ titles. See the rd vignette for details: vignette("rd", package = "roxygen2")

• knitr_chunk_options ⁠<list>⁠: default chunk options used for knitr.

• restrict_image_formats ⁠<flag>⁠: if TRUE then PDF images are only included in the PDF manual, and SVG images are only included in the HTML manual. (This only applies to images supplied via markdown.)

How to set

Either set in DESCRIPTION:

Roxygen: list(markdown = TRUE, load = "installed")

Or if longer, you can put in ⁠/man/roxygen/meta.R⁠:

list(
  markdown = TRUE,
  load = "installed"
)

Expand the embedded inline code

Description

Expand the embedded inline code

Usage

markdown_pass1(text)

Arguments

Details

For example this becomes two: 2. Variables can be set and then reused, within the same tag: The value of x is 100.

We have access to the internal functions of the package, e.g. since this is roxygen2, we can refer to the internal markdown function, and this is TRUE: TRUE.

To insert the name of the current package: roxygen2.

The iris data set has 5 columns: Sepal.Length, Sepal.Width, Petal.Length, Petal.Width, Species.

# Code block demo
x + 1
#> [1] 101

Chunk options:

names(mtcars)
nrow(mtcars)
#>  [1] "mpg"  "cyl"  "disp" "hp"   "drat" "wt"   "qsec" "vs"   "am"   "gear"
#> [11] "carb"
#> [1] 32

Plots:

plot(1:10)

Alternative knitr engines:

```{r}
# comment
this <- 10
is <- this + 10
good <- this + is

Also see vignette("rd-formatting").

Value

Text with R code expanded. A character vector of the same length as the input text.

Dummy page to test roxygen's markdown formatting

Description

Links are very tricky, so I'll put in some links here: Link to a function: roxygenize(). Link to an object: roxygenize (we just treat it like an object here.

Details

Link to another package, function: desc::desc(). Link to another package, non-function: desc::desc.

Link with link text: this great function, roxygenize, or that great function.

In another package: and this one.

This is a table:

Roclet: make NAMESPACE

Description

This roclet automates the production of a NAMESPACE file, which controls the functions imported and exported by your package, as described in Writing R extensions.

The NAMESPACE is generated in two passes: the first generates only import directives (because this can be computed without evaluating package code), and the second generates everything (after the package has been loaded).

See vignette("namespace") for details.

Usage

namespace_roclet()

See Also

tags-namespace for tags that generate NAMESPACE directives.

Examples

# The most common namespace tag is @export, which declares that a function
# is part of the external interface of your package
#' @export
foofy <- function(x, y, z) {
}

# You'll also often find global imports living in a file called
# R/{package}-package.R.
#' @importFrom magrittr %>%
#' @import rlang
NULL

Constructors for S3 object to represent R objects.

Description

These objects are usually created by the parsers, but it is also useful to generate them by hand for testing.

Usage

object(value, alias, type)

Arguments

Default format for data

Description

This function is called to generate the default "Format" section for each data object. The default implementation will return the class and dimension information.

Usage

object_format(x)

Arguments

Value

A character value with valid Rd syntax, or NULL.

Parse a package, file, or inline code

Description

parse_package(), parse_file(), and parse_text() allow you to use roxygen's parsing code to parse the roxygen blocks from a package, file, or character vector of code. env_package() and env_file() provide defaults that generate a temporary environment making it possible to associate each block with the corresponding live object.

Usage

parse_package(path = ".", env = env_package(path))

parse_file(file, env = env_file(file), srcref_path = NULL)

parse_text(text, env = env_file(file))

env_file(file)

env_package(path)

Arguments

Value

A list of roxy_block objects

Roclet: make Rd files

Description

This roclet is the workhorse of roxygen2, producing the .Rd files that R uses to document functions, datasets, packages, classes, and more. See vignette("rd") for details.

Generally you will not call this function directly but will instead use roxygenise() specifying the rd roclet.

Usage

rd_roclet()

See Also

tags-rd, tags-rd-other, tags-reuse, tags-index-crossref for tags provided by this roclet.

Examples

#' The length of a string (in characters)
#'
#' @param x A character vector.
#' @returns An integer vector the same length as `x`.
#'   `NA` strings have `NA` length.
#' @seealso [nchar()]
#' @export
#' @examples
#' str_length(letters)
#' str_length(c("i", "like", "programming", NA))
str_length <- function(x) {
}

Construct an rd_section object

Description

An rd_section represents an Rd command that can appear at the top-level of an Rd document, like ⁠\name{}⁠, ⁠\title{}⁠, ⁠\description{}⁠, or ⁠\section{}⁠.

Usage

rd_section(type, value)

Arguments

Methods

If provide your own rd_section type, you'll also need to define a ⁠format.rd_section_{type}⁠ method that returns formatted Rd output. You may also need to provide a ⁠merge.rd_section_{type}⁠ method if two sections can not be combined with rd_section(x$type, c(x$value, y$value)). See vignette("extending") for more details.

Process roclet on string and capture results.

Description

Useful for testing.

Usage

roc_proc_text(roclet, input, wd = NULL)

Arguments

Build a new roclet.

Description

To create a new roclet, you will need to create a constructor function that wraps roclet, and then implement the methods described below.

Usage

roclet(subclass, ...)

roclet_preprocess(x, blocks, base_path)

roclet_process(x, blocks, env, base_path)

roclet_output(x, results, base_path, ...)

roclet_clean(x, base_path)

roclet_tags(x)

Arguments

Methods

• roclet_preprocess() is called after blocks have been parsed but before code has been evaluated. This should only be needed if your roclet affects how code will evaluated. Should return a roclet.

• roclet_process() called after blocks have been evaluated; i.e. the ⁠@eval⁠ tag has been processed, and the object associated with each block has been determined.

• roclet_output() is given the output from roclet_process() and should produce files on disk.

• roclet_clean() called when roxygenise(clean = TRUE). Should remove any files created by the roclet.

Deprecated methods

roclet_tags() is no longer used; instead provide a roxy_tag_parse() method for each tag.

Create a roclet from a string.

Description

This provides a flexible way of specifying a roclet in a string.

Usage

roclet_find(x)

Arguments

Examples

# rd, namespace, and vignette work for backward compatibility
roclet_find("rd")

# But generally you should specify the name of a function that
# returns a roclet
roclet_find("rd_roclet")

# If it lives in another package, you'll need to use ::
roclet_find("roxygen2::rd_roclet")

# If it takes parameters (which no roclet does currently), you'll need
# to call the function
roclet_find("roxygen2::rd_roclet()")

Blocks

Description

A roxy_block represents a single roxygen2 block.

The ⁠block_*⁠ functions provide a few helpers for common operations:

• block_has_tags(blocks, tags): does block contain any of these tags?

• block_get_tags(block, tags): get all instances of tags

• block_get_tag(block, tag): get single tag. Returns NULL if 0, throws warning if more than 1.

• block_get_tag_value(block, tag): gets val field from single tag.

Usage

roxy_block(tags, file, line, call, object = NULL)

block_has_tags(block, tags)

block_get_tags(block, tags)

block_get_tag(block, tag)

block_get_tag_value(block, tag)

Arguments

Examples

# The easiest way to see the structure of a roxy_block is to create one
# using parse_text:
text <- "
  #' This is a title
  #'
  #' @param x,y A number
  #' @export
  f <- function(x, y) x + y
"

# parse_text() returns a list of blocks, so I extract the first
block <- parse_text(text)[[1]]
block

roxy_tag S3 constructor

Description

roxy_tag() is the constructor for tag objects. roxy_tag_warning() is superseded by warn_roxy_tag(); use to generate a warning that includes the location of the tag.

Usage

roxy_tag(tag, raw, val = NULL, file = NA_character_, line = NA_character_)

roxy_tag_parse(x)

roxy_tag_warning(x, ...)

warn_roxy_tag(tag, message, parent = NULL, envir = parent.frame())

Arguments

Methods

Define a method for roxy_tag_parse to support new tags. See tag_parsers for more details.

Generate Rd output from a tag

Description

Provide a method for this generic if you want a tag to generate output in .Rd files. See vignette("extending") for more details.

Usage

roxy_tag_rd(x, base_path, env)

Arguments

Value

Methods must return a rd_section.

Process a package with the Rd, namespace and collate roclets

Description

This is the workhorse function that uses roclets, the built-in document transformation functions, to build all documentation for a package. See the documentation for the individual roclets, rd_roclet(), namespace_roclet(), and for update_collate(), for more details.

Usage

roxygenize(package.dir = ".", roclets = NULL, load_code = NULL, clean = FALSE)

roxygenise(package.dir = ".", roclets = NULL, load_code = NULL, clean = FALSE)

Arguments

Details

Note that roxygen2 is a dynamic documentation system: it works by inspecting loaded objects in the package. This means that you must be able to load the package in order to document it: see load for details.

Value

NULL

A RoxyTopic is an ordered collection of unique rd_sections

Description

A RoxyTopic object corresponds to a generated .Rd file.

Public fields

Methods

Public methods

• RoxyTopic$format()

• RoxyTopic$is_valid()

• RoxyTopic$has_section()

• RoxyTopic$get_section()

• RoxyTopic$get_value()

• RoxyTopic$get_rd()

• RoxyTopic$get_name()

• RoxyTopic$inherits_from()

• RoxyTopic$inherits_section_from()

• RoxyTopic$add()

• RoxyTopic$add_section()

• RoxyTopic$clone()

Method format()

Format the .Rd file. It considers the sections in particular order, even though Rd tools will reorder them again.

Usage

RoxyTopic$format(...)

Arguments

Returns

Character string.

Method is_valid()

Check if an .Rd file is valid

Usage

RoxyTopic$is_valid()

Returns

Logical flag, TRUE for valid .Rd files

Method has_section()

Check if an .Rd file has a certain section.

Usage

RoxyTopic$has_section(type)

Arguments

Returns

Logical flag.

Method get_section()

Query a section.

Usage

RoxyTopic$get_section(type)

Arguments

Returns

The rd_section object representing the section, or NULL if the topic has no such section.

Method get_value()

Query the value of a section. This is the value of the rd_section object.

Usage

RoxyTopic$get_value(type)

Arguments

Returns

Value.

Method get_rd()

Get the Rd code of a section.

Usage

RoxyTopic$get_rd(type)

Arguments

Returns

Character vector, one element per line.

Method get_name()

Get the value of the name section. This is the name of the Rd topic.

Usage

RoxyTopic$get_name()

Returns

Character scalar.

Method inherits_from()

Query the topics this topic inherits type from.

Usage

RoxyTopic$inherits_from(type)

Arguments

Returns

A character vector of topic names.

Method inherits_section_from()

Query the topics this topic inherits sections from.

Usage

RoxyTopic$inherits_section_from()

Returns

A character vector of topic names.

Method add()

Add one or more sections to the topic.

Usage

RoxyTopic$add(x, block = "???", overwrite = FALSE)

Arguments

Method add_section()

Add a section.

Usage

RoxyTopic$add_section(section, block = "???", overwrite = FALSE)

Arguments

Details

Ensures that each type of name (as given by its name), only appears once in self$sections. This method if for internal use only.

Method clone()

The objects of this class are cloneable with this method.

Usage

RoxyTopic$clone(deep = FALSE)

Arguments

Parse tags

Description

These functions parse the raw tag value, convert a string into a richer R object and storing it in val, or provide an informative warning and returning NULL.

Usage

tag_value(x)

tag_inherit(x)

tag_name(x)

tag_two_part(x, first, second, required = TRUE, markdown = TRUE)

tag_name_description(x)

tag_words(x, min = 0, max = Inf)

tag_words_line(x)

tag_toggle(x)

tag_code(x)

tag_examples(x)

tag_markdown(x)

tag_markdown_with_sections(x)

Arguments

Value

A roxy_tag object with the val field set to the parsed value.

New tag

To create a new ⁠@mytag⁠ define roxy_tag_parse.roxy_tag_mytag(). It should either call one of the functions here, or directly set x$val.

Access metadata about built-in tags

Description

Access metadata about built-in tags

Usage

tags_list(built_in = TRUE)

tags_metadata()

Tags for indexing and cross-references

Description

Learn the full details in vignette('index-crossref').

Key tags:

• ⁠@aliases ${1:alias}⁠: Add additional aliases to the topic. Use NULL to suppress the default alias automatically generated by roxygen2.

• ⁠@concept ${1:concept}⁠: Add additional keywords or phrases to be included in the help.search() index. Each ⁠@concept⁠ should be a single term or phrase.

• ⁠@family ${1:family name}⁠: Generate ⁠@seealso⁠ entries to all other functions in ⁠family name⁠.

• ⁠@keywords ${1:keyword}⁠: Add a standardised keyword, indexed by help.search(). These are generally not useful apart from ⁠@keywords internal⁠ which flags the topic as internal and removes from topic indexes.

• ⁠@references ${1:reference}⁠: Pointers to the related literature. Usually formatted like a bibliography.

• ⁠@seealso [${1:func}()]⁠: Link to other related functions or urls. Usually a sentence or two, or a bulleted list.

Other less frequently used tags:

• ⁠@backref ${1:path}⁠: Manually override the backreference that points from the .Rd file back to the source .R file. Only needed when generating code.

Usage

#' @aliases ${1:alias}
#' @backref ${1:path}
#' @concept ${1:concept}
#' @family ${1:family name}
#' @keywords ${1:keyword}
#' @references ${1:reference}
#' @seealso [${1:func}()]

See Also

Other documentation tags: tags-rd, tags-rd-other, tags-reuse

Tags for managing the NAMESPACE

Description

Learn the full details in vignette('namespace').

Key tags:

• ⁠@export⁠: Export this function, method, generic, or class so it's available outside of the package.

• ⁠@exportS3Method ${1:package}::${2:generic}⁠: Export an S3 method. Only needed when the method is for a generic from a suggested package.

• ⁠@importFrom ${1:package} ${2:function}⁠: Import specific functions from a package.

• ⁠@useDynLib ${1:package}⁠: Import compiled code from another package.

Other less frequently used tags:

• ⁠@evalNamespace ${1:r-code}⁠: Evaluate arbitrary code in the package namespace and insert the results into the NAMESPACE. Should return a character vector of directives.

• ⁠@exportClass ${1:class}⁠: Export an S4 class. For expert use only; in most cases you should use ⁠@export⁠ so roxygen2 can automatically generate the correct directive.

• ⁠@exportMethod ${1:generic}⁠: Export S4 methods. For expert use only; in most cases you should use ⁠@export⁠ so roxygen2 can automatically generate the correct directive.

• ⁠@exportPattern ${1:pattern}⁠: Export all objects matching a regular expression.

• ⁠@import ${1:package}⁠: Import all functions from a package. Use with extreme care.

• ⁠@importClassesFrom ${1:package} ${2:class}⁠: Import S4 classes from another package.

• ⁠@importMethodsFrom ${1:package} ${2:generic}⁠: Import S4 methods from a package.

• ⁠@rawNamespace ${1:namespace directives}⁠: Insert literal text directly into the NAMESPACE.

Usage

#' @evalNamespace ${1:r-code}
#' @export
#' @exportClass ${1:class}
#' @exportMethod ${1:generic}
#' @exportPattern ${1:pattern}
#' @exportS3Method ${1:package}::${2:generic}
#' @import ${1:package}
#' @importClassesFrom ${1:package} ${2:class}
#' @importFrom ${1:package} ${2:function}
#' @importMethodsFrom ${1:package} ${2:generic}
#' @rawNamespace ${1:namespace directives}
#' @useDynLib ${1:package}

Tags for documenting functions

Description

Learn the full details in vignette('rd').

Key tags:

• ⁠@description${1:A short description...} ⁠: A short description of the purpose of the function. Usually around a paragraph, but can be longer if needed.

• ⁠@example ${1:path}.R⁠: Embed examples stored in another file.

• ⁠@examples${1:# example code} ⁠: Executable R code that demonstrates how the function works. Code must run without error.

• ⁠@examplesIf ${1:condition}${2:# example code} ⁠: Run examples only when condition is TRUE.

• ⁠@noRd⁠: Suppress .Rd generation for a block. Use for documentation blocks that should only be visible in the source code.

• ⁠@param ${1:name} ${2:description}⁠: Describe a function input. Should describe acceptable input types and how it affects the output. description is usually one or two sentences but can be as long as needed. Document multiple arguments by separating their names with commas without spaces.

• ⁠@returns ${1:description}⁠: Describe the function's output. Typically will be a 1-2 sentence description of the output type, but might also include discussion of important errors or warnings.

• ⁠@title ${1:title}⁠: A one-line description of the function shown in various indexes. An explicit ⁠@title⁠ is not usually needed as by default it is taken from the first paragraph in the roxygen block.

• ⁠@usage ${1:fun}(${2:arg1, arg2 = default, ...})⁠: Override the default usage generated by roxygen2. Only needed when roxygen2 fails to correctly derive the usage of your function.

Other less frequently used tags:

• ⁠@details${1:Additional details...} ⁠: Additional details about the function. Generally superseded by instead using a level 1 heading.

• ⁠@rawRd ${1:rd}⁠: Insert literal text directly into the .Rd file.

• ⁠@return ${1:description}⁠: Describe the function's output. Superseded in favour of ⁠@returns⁠.

Usage

#' @description${1:A short description...}

#' @details${1:Additional details...}

#' @example ${1:path}.R
#' @examples${1:# example code}

#' @examplesIf ${1:condition}${2:# example code}

#' @noRd
#' @param ${1:name} ${2:description}
#' @rawRd ${1:rd}
#' @return ${1:description}
#' @returns ${1:description}
#' @title ${1:title}
#' @usage ${1:fun}(${2:arg1, arg2 = default, ...})

See Also

Other documentation tags: tags-index-crossref, tags-rd-other, tags-reuse

Tags related to markdown support

Description

Learn the full details in vignette('rd-formatting').

Other less frequently used tags:

• ⁠@md⁠: Force markdown processing for a block.

• ⁠@noMd⁠: Suppress markdown processing for a block.

• ⁠@section ${1:section title}: ⁠: Add an arbitrary section to the documentation. Now generally superseded in favour of using a level 1 heading.

Usage

#' @md
#' @noMd
#' @section ${1:section title}:

Tags for documenting datasets and classes

Description

Learn the full details in vignette('rd-other').

Key tags:

• ⁠@field ${1:name} ${2:description}⁠: Describe a R6 or refClass field.

• ⁠@format ${1:description}⁠: Describe the type/shape of a dataset. If the dataset is a data frame, include a description of each column. If not supplied, will be automatically generated by object_format().

• ⁠@method ${1:generic} ${2:class}⁠: Force a function to be recognised as an S3 method. This affects the default usage and the NAMESPACE directive produced by ⁠@export⁠. Only needed if automatic detection fails.

• ⁠@slot ${1:name} ${2:description}⁠: Describe the slot of an S4 class.

• ⁠@source ${1:description}⁠: Describe where the dataset came from. Provide a link to the original source (if possible) and briefly describe any manipulation that you performed when importing the data.

Usage

#' @field ${1:name} ${2:description}
#' @format ${1:description}
#' @method ${1:generic} ${2:class}
#' @slot ${1:name} ${2:description}
#' @source ${1:description}

See Also

Other documentation tags: tags-index-crossref, tags-rd, tags-reuse

Tags that help you reuse documentation

Description

Learn the full details in vignette('reuse').

Key tags:

• ⁠@describeIn ${1:destination} ${2:description}⁠: Document a function or method in the destination topic.

• ⁠@inherit ${1:source} ${2:components}⁠: Inherit one or more documentation components from another topic. If components is omitted, all supported components will be inherited. Otherwise, specify individual components to inherit by picking one or more of params, return, title, description, details, seealso, sections, references, examples, author, source, note, and format.

• ⁠@inheritDotParams ${1:source} ${2:arg1 arg2 arg3}⁠: Automatically generate documentation for ... when you're passing dots along to another function.

• ⁠@inheritParams ${1:source}⁠: Inherit argument documentation from another function. Only inherits documentation for arguments that aren't already documented locally.

• ⁠@inheritSection ${1:source} ${2:section name}⁠: Inherit a specific named section from another topic.

• ⁠@order ${1:number}⁠: Override the default (lexigraphic) order in which multiple blocks are combined into a single topic.

• ⁠@rdname ${1:topic-name}⁠: Override the file name of generated .Rd file. Can be used to combine multiple blocks into a single documentation topic.

Other less frequently used tags:

• ⁠@eval ${1:r-code}⁠: Evaluate arbitrary code in the package namespace and insert the results back into the block. Should return a character vector of lines.

• ⁠@evalRd ${1:r-code}⁠: Evaluate arbitrary code in the package namespace and insert the results back as into the block. Should return a character vector of lines.

• ⁠@includeRmd man/rmd/${1:filename}.Rmd⁠: Insert the contents of an .Rmd into the current block. Superseded in favour of using a code chunk with a child document.

• ⁠@template ${1:path-to-template}⁠: Use a roxygen2 template. Now superseded in favour of inline R code.

• ⁠@templateVar ${1:name} ${2:value}⁠: Define variables for use in a roxygen2 template.

Usage

#' @describeIn ${1:destination} ${2:description}
#' @eval ${1:r-code}
#' @evalRd ${1:r-code}
#' @includeRmd man/rmd/${1:filename}.Rmd
#' @inherit ${1:source} ${2:components}
#' @inheritDotParams ${1:source} ${2:arg1 arg2 arg3}
#' @inheritParams ${1:source}
#' @inheritSection ${1:source} ${2:section name}
#' @order ${1:number}
#' @rdname ${1:topic-name}
#' @template ${1:path-to-template}
#' @templateVar ${1:name} ${2:value}

See Also

Other documentation tags: tags-index-crossref, tags-rd, tags-rd-other

Update Collate field in DESCRIPTION

Description

By default, R loads files in alphabetical order. Unfortunately not every alphabet puts letters in the same order, so you can't rely on alphabetic ordering if you need one file loaded before another. (This usually doesn't matter but is important for S4, where you need to make sure that classes are loaded before subclasses and generics are defined before methods.). You can override the default alphabetical ordering with ⁠@include before.R⁠, which specify that before.R must be loaded before the current file.

Generally, you will not need to run this function yourself; it should be run automatically by any package that needs to load your R files in collation order.

Usage

update_collate(base_path)

Arguments

Collate

This is not a roclet because roclets need the values of objects in a package, and those values can not be generated unless you've sourced the files, and you can't source the files unless you know the correct order.

If there are no ⁠@include⁠ tags, roxygen2 will leave collate as is. This makes it easier to use roxygen2 with an existing collate directive, but if you remove all your ⁠@include⁠ tags, you'll need to also manually delete the collate field.

Examples

#' If `example-a.R', `example-b.R' and `example-c.R' live in R/
#' and we're in `example-a.R`, then the following @include statement
#' ensures that example-b and example-c are sourced before example-a.
#' @include example-b.R example-c.R
NULL

Re-build outdated vignettes

Description

This roclet rebuilds outdated vignettes with tools::buildVignette, but we no longer recommend it because we no longer recommend storing built vignettes in a package.

By default, it will rebuild all vignettes if the source file is newer than the output pdf or html. (This means it will automatically re-build the vignette if you change the vignette source, but not when you change the R code). If you want finer control, add a Makefile to ⁠vignettes/⁠ and roxygen2 will use that instead.

To prevent RStudio from re-building the vignettes again when checking your package, add --no-build-vignettes to the "Build Source Package" field in your project options.

Usage

vignette_roclet()