diff --git a/dev/news/index.html b/dev/news/index.html index cac79634..b3c17d23 100644 --- a/dev/news/index.html +++ b/dev/news/index.html @@ -81,8 +81,8 @@
Releases

roxygen2 (development version)

roxygen2 7.3.0

CRAN release: 2024-01-11

diff --git a/dev/pkgdown.yml b/dev/pkgdown.yml index b85c640d..606a33e3 100644 --- a/dev/pkgdown.yml +++ b/dev/pkgdown.yml @@ -10,7 +10,7 @@ articles: rd: rd.html reuse: reuse.html roxygen2: roxygen2.html -last_built: 2024-01-22T19:15Z +last_built: 2024-01-22T19:49Z urls: reference: https://roxygen2.r-lib.org/reference article: https://roxygen2.r-lib.org/articles diff --git a/dev/search.json b/dev/search.json index 6b7a9aed..727e697f 100644 --- a/dev/search.json +++ b/dev/search.json @@ -1 +1 @@ -[{"path":[]},{"path":"https://roxygen2.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"our-pledge","dir":"","previous_headings":"","what":"Our Pledge","title":"Contributor Covenant Code of Conduct","text":"members, contributors, leaders pledge make participation community harassment-free experience everyone, regardless age, body size, visible invisible disability, ethnicity, sex characteristics, gender identity expression, level experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, sexual identity orientation. pledge act interact ways contribute open, welcoming, diverse, inclusive, healthy community.","code":""},{"path":"https://roxygen2.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"our-standards","dir":"","previous_headings":"","what":"Our Standards","title":"Contributor Covenant Code of Conduct","text":"Examples behavior contributes positive environment community include: Demonstrating empathy kindness toward people respectful differing opinions, viewpoints, experiences Giving gracefully accepting constructive feedback Accepting responsibility apologizing affected mistakes, learning experience Focusing best just us individuals, overall community Examples unacceptable behavior include: use sexualized language imagery, sexual attention advances kind Trolling, insulting derogatory comments, personal political attacks Public private harassment Publishing others’ private information, physical email address, without explicit permission conduct reasonably considered inappropriate professional setting","code":""},{"path":"https://roxygen2.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"enforcement-responsibilities","dir":"","previous_headings":"","what":"Enforcement Responsibilities","title":"Contributor Covenant Code of Conduct","text":"Community leaders responsible clarifying enforcing standards acceptable behavior take appropriate fair corrective action response behavior deem inappropriate, threatening, offensive, harmful. Community leaders right responsibility remove, edit, reject comments, commits, code, wiki edits, issues, contributions aligned Code Conduct, communicate reasons moderation decisions appropriate.","code":""},{"path":"https://roxygen2.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"scope","dir":"","previous_headings":"","what":"Scope","title":"Contributor Covenant Code of Conduct","text":"Code Conduct applies within community spaces, also applies individual officially representing community public spaces. Examples representing community include using official e-mail address, posting via official social media account, acting appointed representative online offline event.","code":""},{"path":"https://roxygen2.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"enforcement","dir":"","previous_headings":"","what":"Enforcement","title":"Contributor Covenant Code of Conduct","text":"Instances abusive, harassing, otherwise unacceptable behavior may reported community leaders responsible enforcement codeofconduct@posit.co. complaints reviewed investigated promptly fairly. community leaders obligated respect privacy security reporter incident.","code":""},{"path":"https://roxygen2.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"enforcement-guidelines","dir":"","previous_headings":"","what":"Enforcement Guidelines","title":"Contributor Covenant Code of Conduct","text":"Community leaders follow Community Impact Guidelines determining consequences action deem violation Code Conduct:","code":""},{"path":"https://roxygen2.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"id_1-correction","dir":"","previous_headings":"Enforcement Guidelines","what":"1. Correction","title":"Contributor Covenant Code of Conduct","text":"Community Impact: Use inappropriate language behavior deemed unprofessional unwelcome community. Consequence: private, written warning community leaders, providing clarity around nature violation explanation behavior inappropriate. public apology may requested.","code":""},{"path":"https://roxygen2.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"id_2-warning","dir":"","previous_headings":"Enforcement Guidelines","what":"2. Warning","title":"Contributor Covenant Code of Conduct","text":"Community Impact: violation single incident series actions. Consequence: warning consequences continued behavior. interaction people involved, including unsolicited interaction enforcing Code Conduct, specified period time. includes avoiding interactions community spaces well external channels like social media. Violating terms may lead temporary permanent ban.","code":""},{"path":"https://roxygen2.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"id_3-temporary-ban","dir":"","previous_headings":"Enforcement Guidelines","what":"3. Temporary Ban","title":"Contributor Covenant Code of Conduct","text":"Community Impact: serious violation community standards, including sustained inappropriate behavior. Consequence: temporary ban sort interaction public communication community specified period time. public private interaction people involved, including unsolicited interaction enforcing Code Conduct, allowed period. Violating terms may lead permanent ban.","code":""},{"path":"https://roxygen2.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"id_4-permanent-ban","dir":"","previous_headings":"Enforcement Guidelines","what":"4. Permanent Ban","title":"Contributor Covenant Code of Conduct","text":"Community Impact: Demonstrating pattern violation community standards, including sustained inappropriate behavior, harassment individual, aggression toward disparagement classes individuals. Consequence: permanent ban sort public interaction within community.","code":""},{"path":"https://roxygen2.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"attribution","dir":"","previous_headings":"","what":"Attribution","title":"Contributor Covenant Code of Conduct","text":"Code Conduct adapted Contributor Covenant, version 2.1, available https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. Community Impact Guidelines inspired [Mozilla’s code conduct enforcement ladder][https://github.com/mozilla/inclusion]. answers common questions code conduct, see FAQ https://www.contributor-covenant.org/faq. Translations available https://www.contributor-covenant.org/translations.","code":""},{"path":"https://roxygen2.r-lib.org/dev/LICENSE.html","id":null,"dir":"","previous_headings":"","what":"MIT License","title":"MIT License","text":"Copyright (c) 2023 roxygen2 authors Permission hereby granted, free charge, person obtaining copy software associated documentation files (“Software”), deal Software without restriction, including without limitation rights use, copy, modify, merge, publish, distribute, sublicense, /sell copies Software, permit persons Software furnished , subject following conditions: copyright notice permission notice shall included copies substantial portions Software. SOFTWARE PROVIDED “”, WITHOUT WARRANTY KIND, EXPRESS IMPLIED, INCLUDING LIMITED WARRANTIES MERCHANTABILITY, FITNESS PARTICULAR PURPOSE NONINFRINGEMENT. EVENT SHALL AUTHORS COPYRIGHT HOLDERS LIABLE CLAIM, DAMAGES LIABILITY, WHETHER ACTION CONTRACT, TORT OTHERWISE, ARISING , CONNECTION SOFTWARE USE DEALINGS SOFTWARE.","code":""},{"path":"https://roxygen2.r-lib.org/dev/SUPPORT.html","id":null,"dir":"","previous_headings":"","what":"Getting help with roxygen2","title":"Getting help with roxygen2","text":"Thanks using roxygen2. filing issue, places explore pieces put together make process smooth possible.","code":""},{"path":"https://roxygen2.r-lib.org/dev/SUPPORT.html","id":"making-a-reprex","dir":"","previous_headings":"","what":"Making a reprex","title":"Getting help with roxygen2","text":"Start making minimal reproducible example using reprex package. haven’t heard used reprex , ’re treat! Seriously, reprex make R-question-asking endeavors easier (pretty insane ROI five ten minutes ’ll take learn ’s ). additional reprex pointers, check Get help! section tidyverse site. roxygen2 issues can tricky create minimal reprex . two general techniques can help: know source problem, can often recreate using roc_proc_text() text snippet: ’s really helpful can spend little time reducing text absolute minimum. Make sure delete body function (since roxygen2 never looks ), try roxygen2 tag turn. leave tag ’ve confirmed ’s definitely part problem. Issues involve multiple files don’t give useful error messages harder track . cases, sometimes best option create copy package, progressively delete files problem goes away. ’ve done , sometimes ’ll able reduce problem call roc_proc_text() . , ’ll need make minimal package available somewhere internet (preferably github) link issue. can make package small possible, less time ’ll take find bug, time ’ll work .","code":"library(roxygen2) roc_proc_text(rd_roclet(), \" #' Title #' @param #' #' @export foo <- function() {}\" ) #> Error in FUN(X[[i]], ...): subscript out of bounds"},{"path":"https://roxygen2.r-lib.org/dev/SUPPORT.html","id":"where-to-ask","dir":"","previous_headings":"","what":"Where to ask","title":"Getting help with roxygen2","text":"Armed reprex, next step figure ask. ’s question: start community.rstudio.com, /StackOverflow. people answer questions. ’s bug: ’re right place, file issue. ’re sure: let community help figure ! problem bug feature request, can easily return report . opening new issue, sure search issues pull requests make sure bug hasn’t reported /already fixed development version. default, search pre-populated :issue :open. can edit qualifiers (e.g. :pr, :closed) needed. example, ’d simply remove :open search issues repo, open closed.","code":""},{"path":"https://roxygen2.r-lib.org/dev/SUPPORT.html","id":"general-advice","dir":"","previous_headings":"","what":"General advice","title":"Getting help with roxygen2","text":"efficient possible, development tidyverse packages tends bursty. Nothing happens long time, sufficient quantity issues accumulates, ’s burst intense activity focus efforts. makes development efficient avoids expensive context switching problems. process makes good reprex particularly important might multiple months initial report start working . can’t reproduce bug, can’t fix !","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/extending.html","id":"basics","dir":"Articles","previous_headings":"","what":"Basics","title":"Extending roxygen2","text":"Roxygen extensible user-defined roclets. means can take advantage Roxygen’s parser extend @tags. two primary ways extend roxygen2: Add new tag generates new top-level section .Rd files. Add new roclet anything like. vignette introduce key data structures roxygen2, show use two extension points. vignette rough, expected also read roxygen2 source code understand extension points. Hopefully, ’s useful enough help get started, problems, please file issue!","code":"library(roxygen2)"},{"path":"https://roxygen2.r-lib.org/dev/articles/extending.html","id":"key-data-structures","dir":"Articles","previous_headings":"","what":"Key data structures","title":"Extending roxygen2","text":"talk extending roxygen2, need first discuss two important data structures power roxygen: tags blocks.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/extending.html","id":"tags","dir":"Articles","previous_headings":"Key data structures","what":"Tags","title":"Extending roxygen2","text":"tag (list S3 class roxy_tag) represents single tag. following fields: tag: name tag. raw: raw contents tag (.e. everything end tag beginning next). val: parsed value, ’ll come back shortly. file line: location tag package. Used roxy_tag_warning() produce informative error messages. can construct tag objects hand roxy_tag(): However, rarely need , ’ll typically given block object, ’ll see shortly.","code":"roxy_tag(\"name\", \"Hadley\") #> [????:???] @name 'Hadley' {unparsed} str(roxy_tag(\"name\", \"Hadley\")) #> List of 5 #> $ file: chr NA #> $ line: chr NA #> $ raw : chr \"Hadley\" #> $ tag : chr \"name\" #> $ val : NULL #> - attr(*, \"class\")= chr [1:2] \"roxy_tag_name\" \"roxy_tag\""},{"path":"https://roxygen2.r-lib.org/dev/articles/extending.html","id":"blocks","dir":"Articles","previous_headings":"Key data structures","what":"Blocks","title":"Extending roxygen2","text":"block (list S3 class roxy_block) represents single roxygen block. following fields: tags: list roxy_tags. call: R code associated block (usually function call). file line: location R code. object: evaluated R object associated code. easiest way see basic structure roxy_block() generate one parsing roxygen block parse_text():","code":"text <- \" #' This is a title #' #' This is the description. #' #' @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 #> [:8] #> $tag #> [line: 2] @title 'This is a title' {parsed} #> [line: 4] @description 'This is the description.' {parsed} #> [line: 6] @param 'x,y A number' {parsed} #> [line: 7] @export '' {parsed} #> [line: 8] @usage '' {parsed} #> [line: 8] @.formals '' {parsed} #> [line: 8] @backref '' {parsed} #> $call f <- function(x, y) x + y #> $object #> $topic f #> $alias f"},{"path":"https://roxygen2.r-lib.org/dev/articles/extending.html","id":"adding-a-new--rd-tag","dir":"Articles","previous_headings":"","what":"Adding a new .Rd tag","title":"Extending roxygen2","text":"easiest way extend roxygen2 create new tag adds output .Rd files. requires two steps: Define roxy_tag_parse() method describes parse new tag. Define roxy_tag_rd() method describes convert tag .Rd commands. illustrate basic idea, ’ll create new @tip tag create bulleted list tips use function. idea take something like : generate Rd like : first step define method roxy_tag_parse() describes parse tag text. name class roxy_tag_{tag}, case roxy_tag_tip. function takes roxy_tag input, ’s job set x$val convenient parsed value used later roclet. want process text using Markdown can just use tag_markdown(): check works using parse_text(): (explicitly turn Markdown parsing using @md; ’s usually turned package using roxygen options). Next, define method roxy_tag_rd(), must create rd_section(). ’re going create new section called tip. contain character vector tips: additional layer needed can multiple tags type single block, multiple blocks can contribute .Rd file. job rd_section combine tags single top-level Rd section. tag generates rd_section combined previous section using merge(). default merge.rd_section() just concatenates values together (rd_section(x$type, c(x$value, y$value))); can override method need sophisticated behaviour. need define format() method convert object text .Rd file: can now try roclet_text(): Note namespacing ’re defining multiple new tags recommend using package name common prefix.","code":"#' @tip The mean of a logical vector is the proportion of `TRUE` values. #' @tip You can compute means of dates and date-times! \\section{Tips and tricks}{ \\itemize{ \\item The mean of a logical vector is the proportion of \\code{TRUE} values. \\item You can compute means of dates and date-times! } } roxy_tag_parse.roxy_tag_tip <- function(x) { tag_markdown(x) } text <- \" #' Title #' #' @tip The mean of a logical vector is the proportion of `TRUE` values. #' @tip You can compute means of dates and date-times! #' @md f <- function(x, y) { # ... } \" block <- parse_text(text)[[1]] block #> [:7] #> $tag #> [line: 2] @title 'Title' {parsed} #> [line: 4] @tip 'The mean of a logical vector is the proportion ...' {parsed} #> [line: 5] @tip 'You can compute means of dates and date-times!' {parsed} #> [line: 6] @md '' {parsed} #> [line: 7] @usage '' {parsed} #> [line: 7] @.formals '' {parsed} #> [line: 7] @backref '' {parsed} #> $call f <- function(x, y) { ... #> $object #> $topic f #> $alias f str(block$tags[[2]]) #> List of 5 #> $ file: chr \"\" #> $ line: int 4 #> $ tag : chr \"tip\" #> $ raw : chr \"The mean of a logical vector is the proportion of `TRUE` values.\" #> $ val : chr \"The mean of a logical vector is the proportion of \\\\code{TRUE} values.\" #> - attr(*, \"class\")= chr [1:2] \"roxy_tag_tip\" \"roxy_tag\" roxy_tag_rd.roxy_tag_tip <- function(x, base_path, env) { rd_section(\"tip\", x$val) } format.rd_section_tip <- function(x, ...) { paste0( \"\\\\section{Tips and tricks}{\\n\", \"\\\\itemize{\\n\", paste0(\" \\\\item \", x$value, \"\\n\", collapse = \"\"), \"}\\n\", \"}\\n\" ) } topic <- roc_proc_text(rd_roclet(), text)[[1]] topic$get_section(\"tip\") #> \\section{Tips and tricks}{ #> \\itemize{ #> \\item The mean of a logical vector is the proportion of \\code{TRUE} values. #> \\item You can compute means of dates and date-times! #> } #> } #>"},{"path":"https://roxygen2.r-lib.org/dev/articles/extending.html","id":"creating-a-new-roclet","dir":"Articles","previous_headings":"","what":"Creating a new roclet","title":"Extending roxygen2","text":"Creating new roclet usually two part process. First, define new tags roclet work . Second, define roclet tells roxygen process entire package.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/extending.html","id":"custom-tags","dir":"Articles","previous_headings":"Creating a new roclet","what":"Custom tags","title":"Extending roxygen2","text":"example make new @memo tag enable printing memos console roclet runs. choose @memo syntax: example: , first define parse method: check works parse_text():","code":"@memo [Headline] Description @memo [EFFICIENCY] Currently brute-force; find better algorithm. roxy_tag_parse.roxy_tag_memo <- function(x) { if (!grepl(\"^\\\\[.*\\\\].*$\", x$raw)) { roxy_tag_warning(x, \"Invalid memo format\") return() } parsed <- stringi::stri_match(str = x$raw, regex = \"\\\\[(.*)\\\\](.*)\")[1, ] x$val <- list( header = parsed[[2]], message = parsed[[3]] ) x } text <- \" #' @memo [TBI] Remember to implement this! #' @memo [API] Check best API f <- function(x, y) { # ... } \" block <- parse_text(text)[[1]] block #> [:4] #> $tag #> [line: 2] @memo '[TBI] Remember to implement this!' {parsed} #> [line: 3] @memo '[API] Check best API' {parsed} #> [line: 4] @usage '' {parsed} #> [line: 4] @.formals '' {parsed} #> [line: 4] @backref '' {parsed} #> $call f <- function(x, y) { ... #> $object #> $topic f #> $alias f str(block$tags[[1]]) #> List of 5 #> $ file: chr \"\" #> $ line: int 2 #> $ tag : chr \"memo\" #> $ raw : chr \"[TBI] Remember to implement this!\" #> $ val :List of 2 #> ..$ header : chr \"TBI\" #> ..$ message: chr \" Remember to implement this!\" #> - attr(*, \"class\")= chr [1:2] \"roxy_tag_memo\" \"roxy_tag\""},{"path":"https://roxygen2.r-lib.org/dev/articles/extending.html","id":"the-roclet","dir":"Articles","previous_headings":"Creating a new roclet","what":"The roclet","title":"Extending roxygen2","text":"Next, create constructor roclet, uses roclet(). memo roclet doesn’t options simple: give roclet behaviour, need define methods. two methods almost every roclet use: roclet_process() called list blocks, returns object choosing. roclet_output() produces side-effects (usually writing disk) using result roclet_process(). roclet, ’ll roclet_process() collect memo tags named list: roclet_output() just print screen: can test works using roc_proc_text():","code":"memo_roclet <- function() { roclet(\"memo\") } roclet_process.roclet_memo <- function(x, blocks, env, base_path) { results <- list() for (block in blocks) { tags <- block_get_tags(block, \"memo\") for (tag in tags) { msg <- paste0(\"[\", tag$file, \":\", tag$line, \"] \", tag$val$message) results[[tag$val$header]] <- c(results[[tag$val$header]], msg) } } results } roclet_output.roclet_memo <- function(x, results, base_path, ...) { for (header in names(results)) { messages <- results[[header]] cat(paste0(header, \": \", \"\\n\")) cat(paste0(\" * \", messages, \"\\n\", collapse = \"\")) } invisible(NULL) } results <- roc_proc_text(memo_roclet(), \" #' @memo [TBI] Remember to implement this! #' @memo [API] Check best API f <- function(x, y) { # ... } #' @memo [API] Consider passing z option g <- function(x, y) { # ... } \") roclet_output(memo_roclet(), results) #> TBI: #> * [:2] Remember to implement this! #> API: #> * [:3] Check best API #> * [:8] Consider passing z option"},{"path":"https://roxygen2.r-lib.org/dev/articles/extending.html","id":"adding-a-roclet-to-your-workflow","dir":"Articles","previous_headings":"","what":"Adding a roclet to your workflow","title":"Extending roxygen2","text":"use roclet developing package, call yourPackage::roclet function creates roclet, e.g. memo_roclet . can also add roclet target package’s DESCRIPTION file, like : Optionally, can add roclet package target package Suggests: dependency: don’t , help developers working target package.","code":"roxygen2::roxygenize(roclets = \"yourPackage::roclet\") Roxygen: list(roclets = c(\"collate\", \"rd\", \"namespace\", \"yourPackage::roclet\")) usethis::use_dev_package(\"yourPackage\", type = \"Suggests\", remote = \"yourGithubID/yourPackage\")"},{"path":"https://roxygen2.r-lib.org/dev/articles/index-crossref.html","id":"see-also","dir":"Articles","previous_headings":"","what":"See also","title":"Indexing and cross-references","text":"@seealso allows point useful resources, either web (using url) related functions (function link like [function_name()]). sum(), might look like:","code":"#' @seealso [prod()] for products, [cumsum()] for cumulative sums, and #' [colSums()]/[rowSums()] marginal sums over high-dimensional arrays."},{"path":"https://roxygen2.r-lib.org/dev/articles/index-crossref.html","id":"family","dir":"Articles","previous_headings":"","what":"Family","title":"Indexing and cross-references","text":"family related functions, can use @family {family} cross-reference function every member family. function can member multiple families. default @family {family}, generate see also text “{family}:”, @family name plural (.e., “model building helpers” “model building helper”). want override default title, can provide rd_family_title element list stored man/roxygen/meta.R:","code":"list( rd_family_title = list(aggregations = \"Aggregation functions\") )"},{"path":"https://roxygen2.r-lib.org/dev/articles/index-crossref.html","id":"references","dir":"Articles","previous_headings":"","what":"References","title":"Indexing and cross-references","text":"object ’re documenting connections scientific literature, use @reference provide citation.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/index-crossref.html","id":"aliases","dir":"Articles","previous_headings":"","what":"Aliases","title":"Indexing and cross-references","text":"? help() look topic aliases; ?foo find topic contains foo alias. roxygen2 generates default alias based object ’re documenting. can add additional aliases @aliases alias1 alias2 alias3 remove default alias @aliases NULL.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/index-crossref.html","id":"search","dir":"Articles","previous_headings":"","what":"Search","title":"Indexing and cross-references","text":"well looking aliases, help.search() ??? also look @title, @keywords, @concepts tags. @keywords adds standard keywords, must present file.path(R.home(\"doc\"), \"KEYWORDS\"). @concept adds arbitrary key words phrases. @concept contain single word phrase. Generally speaking, @keywords @concepts terribly useful people find documentation using Google, R’s built-search. ’s one exception: @keywords internal. ’s useful removes function documentation index; ’s useful functions aimed primarily developers, typical users package.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/index-crossref.html","id":"back-references","dir":"Articles","previous_headings":"","what":"Back references","title":"Indexing and cross-references","text":"original source location added comment second line generated .Rd file following form: roxygen2 tries capture locations documentation assembled. code generates R code Roxygen comments (e.g., Rcpp package), @backref tag provided. allows specifying “true” source documentation, substitute default list source files. Use one tag per source file:","code":"% Please edit documentation in ... #' @backref src/file.cpp #' @backref src/file.h"},{"path":"https://roxygen2.r-lib.org/dev/articles/namespace.html","id":"exports","dir":"Articles","previous_headings":"","what":"Exports","title":"Managing imports and exports","text":"order users use function1 package, must export . cases, can just use @export tag, roxygen2 automatically figure NAMESPACE directive (.e. export(), exportS3method(), exportClasses(), orexportMethods()) need. Note datasets never exported found NAMESPACE. Instead, datasets either automatically exported set LazyData: true DESCRIPTION, made available calling data() .","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/namespace.html","id":"functions","dir":"Articles","previous_headings":"Exports","what":"Functions","title":"Managing imports and exports","text":"function exported user facing; exported ’s internal use . export function, must also document , since people use , need careful later change function interface.","code":"#' Add two numbers together #' #' @param x,y A pair of numbers. #' @export add <- function(x, y) { x + y }"},{"path":"https://roxygen2.r-lib.org/dev/articles/namespace.html","id":"s3","dir":"Articles","previous_headings":"Exports","what":"S3","title":"Managing imports and exports","text":"S3 generic works like regular R function export following advice : want users call , export; otherwise, don’t. S3 methods regular functions special naming scheme, “export” works bit differently. S3 methods exported sense calling generic appropriate class call method; user can’t directly access method definition typing name. technically correctly term say method registered generics can find . must register, .e. @export, every S3 method regardless whether generic exported. roxygen2 warn forgotten. exporting method way, can use @exportS3Method NULL suppress warning. four options documenting S3 method: Don’t document ; ’s required, needed simple generics user won’t care details. method particularly complex many arguments generic , can document file. case, just document ’s function. can use @rdname document methods generic. good option ’s generic, ’re providing bunch methods different classes. can use @rdname document methods class. typically least appealing option different generics different arguments, leading cluttered potentially confusing page. Typically, write methods generics either defined current package package hard dependency2 package. Sometimes, however, want write method suggested dependency. case, @export work assumes generic included imported NAMESPACE. Instead, use @exportS3Method. use “delayed” method registration, means method registered suggested package loaded. use @exportS3Method must provide package generic name following format:","code":"#' Take an object to bizarro world #' #' @param x A vector. #' @export bizarro <- function(x, ...) { UseMethod(\"bizarro\") } #' @export bizarro.character <- function(x, ...) { letters <- strsplit(x, \"\") letters_rev <- lapply(letters, rev) vapply(letters_rev, paste, collapse = \"\", FUN.VALUE = character(1)) } #' Take an object to bizarro world #' #' @description #' This is an S3 generic. This package provides methods for the #' following classes: #' #' * `character`: reverses the order of the letters in each element of #' the vector. #' #' @param x A vector. #' @export bizarro <- function(x, ...) { UseMethod(\"bizarro\") } #' @export #' @rdname bizarro bizarro.character <- function(x, ...) { letters <- strsplit(x, \"\") letters_rev <- lapply(letters, rev) vapply(letters_rev, paste, collapse = \"\", FUN.VALUE = character(1)) } #' @exportS3Method pkg::generic generic.foo <- function(x, ...) { }"},{"path":"https://roxygen2.r-lib.org/dev/articles/namespace.html","id":"s4","dir":"Articles","previous_headings":"Exports","what":"S4","title":"Managing imports and exports","text":"Classes: export class object want others able extend . Generics: treat like function @export user facing. Methods: need @export method, generic lives another package. Unlike S3, must document S4 methods. method details often important, ’s common use @rdname put documentation unimportant methods single topic @keywords internal.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/namespace.html","id":"manual-exports","dir":"Articles","previous_headings":"Exports","what":"Manual exports","title":"Managing imports and exports","text":"@export automatically generate correct NAMESPACE directive, can use one tags exercise greater control: @export foo generates export(foo) @exportS3Method generic method generates S3method(generic, method) @exportClass foo generates exportClasses(foo) @exportMethod foo generates exportMethods(foo) @exportPattern foo generates exportPattern(foo) even specialised cases can use @rawNamespace code inserts code literally NAMESPACE. useful need conditional import export, e.g. need automate , @evalNamespace fun() evaluate fun() package environment insert results NAMESPACE. Note evalNamespace() run package environment, can generate exports, imports.","code":"# From dplyr: #' @rawNamespace import(vctrs, except = data_frame) # From backports: #' @rawNamespace if (getRversion() < \"4.0.0\") export(stopifnot)"},{"path":"https://roxygen2.r-lib.org/dev/articles/namespace.html","id":"imports","dir":"Articles","previous_headings":"","what":"Imports","title":"Managing imports and exports","text":"NAMESPACE also controls functions packages made available package.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/namespace.html","id":"functions-1","dir":"Articles","previous_headings":"Imports","what":"Functions","title":"Managing imports and exports","text":"using just functions another package, recommending adding package Imports: field DESCRIPTION file calling functions explicitly using ::, e.g., pkg::fun(). repetition package name becomes annoying can @importFrom drop ::: Imports affect every function package, ’s common collect central place, like {packagename}-package.R. automated usethis::use_import_from(). Note use NULL : must provide something roxygen2 document, use NULL place holder. possible, generally recommended import functions package @import package. risky import functions one package, might ok today, future packages might end function name, users get warning every time package loaded.","code":"my_function <- function(x, y) { pkg::fun(x) * y } #' @importFrom pkg fun my_function <- function(x, y) { fun(x) * y } #' @importFrom pkg fun1 fun2 #' @importFrom pkg2 fun3 #' @importFrom pkg3 fun4 NULL #> NULL"},{"path":"https://roxygen2.r-lib.org/dev/articles/namespace.html","id":"s3-1","dir":"Articles","previous_headings":"Imports","what":"S3","title":"Managing imports and exports","text":"S3 generics just functions, rules functions apply. S3 methods always accompany generic, long can access generic (either implicitly explicitly), methods also available. words, don’t need anything special S3 methods. long ’ve imported generic, methods also available.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/namespace.html","id":"s4-1","dir":"Articles","previous_headings":"Imports","what":"S4","title":"Managing imports and exports","text":"use classes defined another package, place @importClassesFrom package ClassA ClassB ... next classes inherit imported classes, next methods implement generic imported classes. use generics defined another package, place @importMethodsFrom package GenericA GenericB ... next methods use imported generics.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/namespace.html","id":"compiled-code","dir":"Articles","previous_headings":"Imports","what":"Compiled code","title":"Managing imports and exports","text":"import compiled code another package, use @useDynLib @useDynLib package imports compiled functions. @useDynLib package routinea routineb imports selected compiled functions. @useDynLib specification containing comma, e.g. @useDynLib mypackage, .registration = TRUE inserted NAMESPACE, e.g. useDynLib(mypackage, .registration = TRUE)","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"enabling-markdown-support","dir":"Articles","previous_headings":"","what":"Enabling markdown support","title":"(R)Markdown support","text":"turn Markdown support package, insert entry DESCRIPTION file package: use devtools/usethis, automatically inserted create new package. ’re updating existing package, recommend usethis::use_roxygen_md() modify DESCRIPTION prompt use roxygen2md package convert existing docs. needed, can also use @md @noMd turn markdown support documentation block. example roxygen chunk uses Markdown.","code":"Roxygen: list(markdown = TRUE) #' Use roxygen to document a package #' #' This function is a wrapper for the [roxygen2::roxygenize()] function from #' the roxygen2 package. See the documentation and vignettes of #' that package to learn how to use roxygen. #' #' @param pkg package description, can be path or package name. See #' [as.package()] for more information. #' @param clean,reload Deprecated. #' @inheritParams roxygen2::roxygenise #' @seealso [roxygen2::roxygenize()], `browseVignettes(\"roxygen2\")` #' @export"},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"basic-syntax","dir":"Articles","previous_headings":"","what":"Basic syntax","title":"(R)Markdown support","text":"roxygen uses commonmark package, based “CommonMark Reference Implementation”. See https://commonmark.org/help/ parser markdown language supports. important details described .","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"sections-and-subsections","dir":"Articles","previous_headings":"Basic syntax","what":"Sections and subsections","title":"(R)Markdown support","text":"usual Markdown heading markup creates sections subsections. Top level headings (e.g. # title) create sections \\section{} Rd tag. largely supersedes use older @section tag. Top-level headings can appear @description @details tags. Since @details can appear multiple times block, can always precede ‘#’ section @details, want put near end block, @return example: Top level sections placed fixed position manual page, parameters details, \\note{}, \\seealso{} \\examples{}. order roxygen block. Headings level two may appear inside roxygen tag formats lines text, e.g. @description, @details, @return, create subsections \\subsection{} Rd tag.","code":"#' @details #' Trim the leading and trailing whitespace from a character vector. #' #' @param x Character vector. #' @return Character vector, with the whitespace trimmed. #' #' @details # This will be a new section #' ... #' @details #' ## Subsection within details #' ### Sub-subsection #' ... text ..."},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"inline-formatting","dir":"Articles","previous_headings":"Basic syntax","what":"Inline formatting","title":"(R)Markdown support","text":"emphasis, put text asterisks underline characters. strong text, use two asterisks sides.","code":"#' @references #' Robert E Tarjan and Mihalis Yannakakis. (1984). Simple #' linear-time algorithms to test chordality of graphs, test acyclicity #' of hypergraphs, and selectively reduce acyclic hypergraphs. #' *SIAM Journal of Computation* **13**, 566-579. #' See `::is_falsy` for the definition of what is _falsy_ #' and what is _truthy_."},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"code","dir":"Articles","previous_headings":"Basic syntax","what":"Code","title":"(R)Markdown support","text":"Inline code supported via backticks. blocks code, put code triple backticks: can also include executable code chunks using usual knitr syntax. See details.","code":"#' @param ns Optionally, a named vector giving prefix-url pairs, as #' produced by `xml_ns`. If provided, all names will be explicitly #' qualified with the ns prefix, i.e. if the element `bar` is defined ... #' ``` #' pkg <- make_packages( #' foo1 = { f <- function() print(\"hello!\") ; d <- 1:10 }, #' foo2 = { f <- function() print(\"hello again!\") ; d <- 11:20 } #' ) #' foo1::f() #' foo2::f() #' foo1::d #' foo2::d #' dispose_packages(pkg) #' ```"},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"lists","dir":"Articles","previous_headings":"Basic syntax","what":"Lists","title":"(R)Markdown support","text":"Regular Markdown lists recognized converted \\enumerate{} \\itemize{} lists: Note leave empty line list. different Markdown parsers.","code":"#' There are two ways to use this function: #' 1. If its first argument is not named, then it returns a function #' that can be used to color strings. #' 1. If its first argument is named, then it also creates a #' style with the given name. This style can be used in #' `style`. One can still use the return value #' of the function, to create a style function. #' The style (the `...` argument) can be anything of the #' following: #' * An R color name, see `colors()`. #' * A 6- or 8-digit hexa color string, e.g. `#ff0000` means #' red. Transparency (alpha channel) values are ignored. #' * A one-column matrix with three rows for the red, green, #' and blue channels, as returned by [grDevices::col2rgb()]."},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"tables","dir":"Articles","previous_headings":"Basic syntax","what":"Tables","title":"(R)Markdown support","text":"Use GFM table formatting: default, columns left-aligned. Use colons generate right center aligned columns:","code":"| foo | bar | | --- | --- | | baz | bim | | left | center | right | | :--- | :----: | ----: | | 1 | 2 | 3 |"},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"links","dir":"Articles","previous_headings":"Basic syntax","what":"Links","title":"(R)Markdown support","text":"Markdown hyperlinks work usual: URLs inside angle brackets also automatically converted hyperlinks:","code":"#' See more about the Markdown markup at the #' [Commonmark web site](http://commonmark.org/help) #' The main R web site is at ."},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"images","dir":"Articles","previous_headings":"Basic syntax","what":"Images","title":"(R)Markdown support","text":"Markdown syntax inline images works. image files must man/figures directory:","code":"#' Here is an example plot: #' ![](example-plot.jpg \"Example Plot Title\")"},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"function-links","dir":"Articles","previous_headings":"","what":"Function links","title":"(R)Markdown support","text":"Markdown notation can also used create links help topics. two basic forms: [topic]: link text automatically generated topic. [text][topic]: supply link text.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"default-link-text","dir":"Articles","previous_headings":"Function links","what":"Default link text","title":"(R)Markdown support","text":"First explore simplest form: [ref]. presence trailing parentheses, e.g., [func()], signals target func function, causes two things happen: link text func() automatically typeset code. parentheses stripped derived Rd link target.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"custom-link-text","dir":"Articles","previous_headings":"Function links","what":"Custom link text","title":"(R)Markdown support","text":"Use second form [text][ref] link topic specified ref, text link text.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"operators","dir":"Articles","previous_headings":"Function links","what":"Operators","title":"(R)Markdown support","text":"Links operators objects contain special characters currently work. link (e.g.) %>% operator magrittr package, instead [magrittr::%>%], need use Rd notation: \\code{\\link[magrittr]{\\%>\\%}}.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"code-chunks","dir":"Articles","previous_headings":"","what":"Code chunks","title":"(R)Markdown support","text":"can insert executable code ```{r}, just like knitr documents. example: becomes: code run every time call roxygenize() (devtools::document()) generate Rd files. potentially makes roxygenize() (much) slower. Either avoid expensive computations, turn knitr caching cache = TRUE. Make sure omit cache package usethis::use_build_ignore(). Note knitr call appropriate print() (available) knitr::knit_print() method result. may generate markdown supported roxygen2. needed, override automatic methods R calls return markdown character vector, wrapped knitr::asis_output().","code":"#' @title Title #' @details Details #' ```{r lorem} #' 1+1 #' ``` #' @md foo <- function() NULL % Generated by roxygen2: do not edit by hand % Please edit documentation in ./ \\name{foo} \\alias{foo} \\title{Title} \\usage{ foo() } \\description{ Title } \\details{ Details \\if{html}{\\out{
}}\\preformatted{1+1 #> [1] 2 }\\if{html}{\\out{<\/div>}} }"},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"chunk-options","dir":"Articles","previous_headings":"Code chunks","what":"Chunk options","title":"(R)Markdown support","text":"Code blocks support knitr chunk options, e.g. keep output several expressions together, can specify results=\"hold\": knitr chunk options reset start every code block, want change , ’ll specify every chunk. currently error, fig.path, fig.process, comment, collapse. Alternatively, can set knitr_chunk_options option override defaults, add new chunk options used whole package. See ?load_options specifying roxygen2 options.","code":"#' ```{r results=\"hold\"} #' names(mtcars) #' nrow(mtcars) #' ```"},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"images-1","dir":"Articles","previous_headings":"Code chunks","what":"Images","title":"(R)Markdown support","text":"Plots create .png files man/figures directory file names coming chunk name. aware plots can quickly increase size package leading challenges CRAN submission. default roxygen2 includes PDF images PDF manual, SVG images HTML manual. want avoid restriction, set restrict_image_formats roxygen2 option FALSE, see ?load_options.","code":"#' ```{r iris-pairs-plot} #' pairs(iris[1:4], main = \"Anderson's Iris Data -- 3 species\", #' pch = 21, bg = c(\"red\", \"green3\", \"blue\")[unclass(iris$Species)]) #' ```"},{"path":[]},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"some-rd-tags-cant-contain-markdown","dir":"Articles","previous_headings":"Possible problems","what":"Some Rd tags can’t contain markdown","title":"(R)Markdown support","text":"mixing Rd Markdown notation, Rd tags may contain Markdown markup, ones can : \\acronym, \\code, \\command, \\CRANpkg, \\deqn, \\doi, \\dontrun, \\dontshow, \\donttest, \\email, \\env, \\eqn, \\figure, \\file, \\, \\ifelse, \\kbd, \\link, \\linkS4class, \\method, \\mjeqn, \\mjdeqn, \\mjseqn, \\mjsdeqn, \\mjteqn, \\mjtdeqn, \\newcommand, \\option, \\, \\packageAuthor, \\packageDescription, \\packageDESCRIPTION, \\packageIndices, \\packageMaintainer, \\packageTitle, \\pkg, \\PR, \\preformatted, \\renewcommand, \\S3method, \\S4method, \\samp, \\special, \\testonly, \\url, \\var, \\verb.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"mixing-markdown-and-rd-markup","dir":"Articles","previous_headings":"Possible problems","what":"Mixing Markdown and Rd markup","title":"(R)Markdown support","text":"Note turning Markdown turn standard Rd syntax. suggest use regular Rd tags Markdown roxygen chunk necessary. two parsers occasionally interact, Markdown parser can pick reformat Rd syntax, causing error, corrupted manuals.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"leading-white-space","dir":"Articles","previous_headings":"Possible problems","what":"Leading white space","title":"(R)Markdown support","text":"Leading white space interpreted commonmark parser, ignored Rd parser (except \\preformatted{}). Make sure include leading white space intentionally, example, nested lists.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"spurious-lists","dir":"Articles","previous_headings":"Possible problems","what":"Spurious lists","title":"(R)Markdown support","text":"commonmark parser require empty line lists, might lead unintended lists line starts number followed dot, asterisk followed white space:","code":"#' You can see more about this topic in the book cited below, on page #' 42. Clearly, the numbered list that starts here is not intentional."},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-other.html","id":"datasets","dir":"Articles","previous_headings":"","what":"Datasets","title":"Documenting other objects","text":"Datasets stored data/, regular R objects package. means need document slightly different way: instead documenting data directly, quote dataset’s name. Note use two additional tags particularly useful documenting data: @format, gives overview structure dataset. include definition list describes variable. ’s currently way generate Markdown, one places ’ll need Rd markup directly. @source got data form, often URL.","code":"#' Prices of over 50,000 round cut diamonds #' #' A dataset containing the prices and other attributes of almost 54,000 #' diamonds. The variables are as follows: #' #' @format A data frame with 53940 rows and 10 variables: #' \\describe{ #' \\item{price}{price in US dollars ($326--$18,823)} #' \\item{carat}{weight of the diamond (0.2--5.01)} #' \\item{cut}{quality of the cut (Fair, Good, Very Good, Premium, Ideal)} #' \\item{color}{diamond colour, from D (best) to J (worst)} #' \\item{clarity}{a measurement of how clear the diamond is (I1 (worst), SI2, #' SI1, VS2, VS1, VVS2, VVS1, IF (best))} #' \\item{x}{length in mm (0--10.74)} #' \\item{y}{width in mm (0--58.9)} #' \\item{z}{depth in mm (0--31.8)} #' \\item{depth}{total depth percentage = z / mean(x, y) = 2 * z / (x + y) (43--79)} #' \\item{table}{width of top of diamond relative to widest point (43--95)} #' } #' #' @source {ggplot2} tidyverse R package."},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-other.html","id":"packages","dir":"Articles","previous_headings":"","what":"Packages","title":"Documenting other objects","text":"well documenting every object inside package, can also document package documenting special sentinel \"_PACKAGE\". automatically includes information parsed DESCRIPTION, including title, description, list authors, useful URLs. recommend placing package documentation {pkgname}-package.R, @keywords internal. Use usethis::use_package_doc() set automatically. ’s example: Package documentation good place put # Package options documents options used package. notes: default, aliases added ?pkgname package?pkgname find package help. ’s existing function called pkgname, use @aliases {pkgname}-package NULL override default. Use @references point published material package users might find helpful.","code":"#' @keywords internal \"_PACKAGE\""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-other.html","id":"s3","dir":"Articles","previous_headings":"","what":"S3","title":"Documenting other objects","text":"S3 generics regular functions, document . necessary, include section provides additional details developers implementing methods. S3 classes formal definition, document constructor. choice whether document S3 methods. Generally, ’s necessary document straightforward methods common generics like print(). (, however, always @export S3 methods). method complicated, document setting @rdname @describeIn. complicated methods, might document file (.e. @rdname generic.class; simpler methods might document generic (.e. @describeIn generic). Learn tags vignette(\"reuse\"). Generally, roxygen2 automatically figure generic method belongs , need use @method ambiguity. example, .equal.data.frame() equal.data.frame method (), data.frame method .equal()?. happens , disambiguate (e.g.) @method .equal data.frame.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-other.html","id":"s4","dir":"Articles","previous_headings":"","what":"S4","title":"Documenting other objects","text":"S4 generics also functions, document . Document S4 classes adding roxygen block setClass(). Use @slot document slots class. ’s simple example: S4 methods little complicated. Unlike S3 methods, S4 methods must documented. can document three places: class. appropriate corresponding generic uses single dispatch created class. generic. appropriate generic uses multiple dispatches control . file. appropriate method complex. either two options don’t apply. Use either @rdname @describeIn control method documentation goes. See next section details.","code":"#' An S4 class to represent a bank account #' #' @slot balance A length-one numeric vector Account <- setClass(\"Account\", slots = list(balance = \"numeric\") )"},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-other.html","id":"r6","dir":"Articles","previous_headings":"","what":"R6","title":"Documenting other objects","text":"R6 methods can documented -line, .e. method’s documentation comments come right definition method. Method documentation can use @description, @details, @param, @return @examples tags. used create subsection method, within separate ‘Methods’ section. roxygen comment lines method documentation must appear tag. @param tags appear class definition automatically inherited methods, needed. R6 fields active bindings can make use @field tag. documentation also -line. roxygen2 checks public methods, public fields, active bindings method arguments documented, issues warnings otherwise. turn special handling R6 classes go back roxygen2 6.x.x behavior, use r6 = FALSE option DESCRIPTION, Roxygen entry: Roxygen: list(r6 = FALSE). roxygen2 automatically generates additional sections R6 class: section information superclass(es) class, links. HTML includes list inherited methods, links. ‘Examples’ section contains class method examples. section run R CMD check, method examples must work without errors. example R6 tutorial:","code":"#' R6 Class Representing a Person #' #' @description #' A person has a name and a hair color. #' #' @details #' A person can also greet you. Person <- R6::R6Class(\"Person\", public = list( #' @field name First or full name of the person. name = NULL, #' @field hair Hair color of the person. hair = NULL, #' @description #' Create a new person object. #' @param name Name. #' @param hair Hair color. #' @return A new `Person` object. initialize = function(name = NA, hair = NA) { self$name <- name self$hair <- hair self$greet() }, #' @description #' Change hair color. #' @param val New hair color. #' @examples #' P <- Person(\"Ann\", \"black\") #' P$hair #' P$set_hair(\"red\") #' P$hair set_hair = function(val) { self$hair <- val }, #' @description #' Say hi. greet = function() { cat(paste0(\"Hello, my name is \", self$name, \".\\n\")) } ) )"},{"path":"https://roxygen2.r-lib.org/dev/articles/rd.html","id":"basics","dir":"Articles","previous_headings":"","what":"Basics","title":"Documenting functions","text":"roxygen block sequence lines starting #' (optionally preceded white space). first lines block called introduction forms title, description, details, described . introduction continues first tag. Tags start @, like @details @param. Tags must appear beginning line content extends start next tag end block. Text within description tags can formatted using Markdown Rd commands; see vignette(\"rd-formatting\") details. block ends hits R code, usually function object assignment. Blocks ignore empty lines, including lines made non-roxygen comments. need separate two blocks, use NULL. want use roxygen2 documentation tags without generating .Rd file, can use @noRd suppress file generation given topic. useful want use roxygen2 conventions documenting internal function; people reading source doc able read docs.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd.html","id":"the-introduction","dir":"Articles","previous_headings":"","what":"The introduction","title":"Documenting functions","text":"documentation block starts text defines title, description, details. ’s example showing documentation sum() might look like written roxygen: introductory block broken follows: first sentence title: ’s see look help(package = mypackage) shown top help file. generally fit one line, written sentence case, end full stop. second paragraph description: comes first documentation briefly describe function . third subsequent paragraphs go details: (often long) section comes argument description provide important details function operates. details optional. can also use explicit @title, @description, @details tags. unnecessary unless want multi-paragraph description, bulleted list, exotic structure.","code":"#' Sum of vector elements #' #' `sum` returns the sum of all the values present in its arguments. #' #' This is a generic function: methods can be defined for it directly #' or via the [Summary()] group generic. For this to work properly, #' the arguments `...` should be unnamed, and dispatch is on the #' first argument. sum <- function(..., na.rm = TRUE) {} #' Sum of vector elements #' #' @description #' `sum` returns the sum of all the values present in its arguments. #' #' @details #' This is a generic function: methods can be defined for it directly #' or via the [Summary()] group generic. For this to work properly, #' the arguments `...` should be unnamed, and dispatch is on the #' first argument."},{"path":"https://roxygen2.r-lib.org/dev/articles/rd.html","id":"functions","dir":"Articles","previous_headings":"","what":"Functions","title":"Documenting functions","text":"Functions commonly documented objects. Functions require three tags: @param, @returns, @examples.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd.html","id":"inputs","dir":"Articles","previous_headings":"Functions","what":"Inputs","title":"Documenting functions","text":"Use @param name description describe input function. description provide succinct summary parameter type (e.g. string, numeric vector), obvious name, parameter . description sentence start capital letter end full stop. can span multiple lines (even paragraphs) necessary. parameters must documented. two arguments tightly coupled, can document one place separating names commas (spaces). example, document x y, can say @param x,y Numeric vectors.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd.html","id":"outputs","dir":"Articles","previous_headings":"Functions","what":"Outputs","title":"Documenting functions","text":"@returns description describes output function. Briefly describe type/shape output, details. functions must documented return value initial CRAN submission.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd.html","id":"examples","dir":"Articles","previous_headings":"Functions","what":"Examples","title":"Documenting functions","text":"@examples provides executable R code showing use function practice. important part documentation many people look examples reading anything. Example code must work without errors run automatically part R CMD check. purpose illustration, ’s often useful include code causes error. can wrapping code try() using \\dontrun{} exclude executed example code. finer control, can use @examplesIf: generates way, code evaluating whether example can run shown users reading help, still prevents R CMD check failures. Instead including examples directly documentation, can put separate files use @example path/relative//package/root insert documentation. functions must examples initial CRAN submission.","code":"#' @examplesIf interactive() #' browseURL(\"https://roxygen2.r-lib.org\") \\examples{ \\dontshow{if (interactive() (if (getRversion() >= \"3.4\") withAutoprint else force)(\\{ # examplesIf} gh_organizations(since = 42) \\dontshow{\\}) # examplesIf} }"},{"path":"https://roxygen2.r-lib.org/dev/articles/rd.html","id":"usage","dir":"Articles","previous_headings":"Functions","what":"Usage","title":"Documenting functions","text":"case, function usage (appears beneath description generates docs) automatically derived function specification. cases , please file issue use @usage override default want. want suppress usage altogether (sometimes useful internal deprecated functions), can use @usage NULL.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"multiple-functions-in-the-same-topic","dir":"Articles","previous_headings":"","what":"Multiple functions in the same topic","title":"Reusing documentation","text":"can document multiple functions file using either @rdname @describeIn tag. ’s technique best used care: documenting many functions one place leads confusion. Use functions (similar) arguments.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"rdname","dir":"Articles","previous_headings":"Multiple functions in the same topic","what":"@rdname","title":"Reusing documentation","text":"Use @rdname 1 include multiple functions page. Tags (e.g. @title, @description, @examples) combined, across blocks often yields text hard understand. recommend make one block contains title, description, common parameters, examples , document individual parameters blocks. two basic ways . can create standalone documentation block add functions . typically works best family related functions want link family functions (.e. trig examples ). Alternatively, can add docs existing function. tends work better “primary” function variants helpers.","code":"#' Trigonometric approximations #' @param x Input, in radians. #' @name trig NULL #> NULL #' @rdname trig #' @export sin_ish <- function(x) x - x^3 / 6 #' @rdname trig #' @export cos_ish <- function(x) 1 - x^2 / 2 #' @rdname trig #' @export tan_ish <- function(x) x + x^3 / 3 #' Logarithms #' #' @param x A numeric vector #' @export log <- function(x, base) ... #' @rdname log #' @export log2 <- function(x) log(x, 2) #' @rdname log #' @export ln <- function(x) log(x, exp(1))"},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"describein","dir":"Articles","previous_headings":"Multiple functions in the same topic","what":"@describeIn","title":"Reusing documentation","text":"alternative @rdname @describeIn. slightly different syntax well topic name, also provide brief description function, like @describein topic one sentence description. primary difference @rdname @describeIn, @describeIn creates new section containing bulleted list function, along description. uses number heuristics determine heading section, depending ’re documenting related functions, methods generic, methods class. general, longer recommend @describeIn don’t think heuristics uses good thoughtful hand-crafted summary. ’re currently using @describeIn, can general replace @rdname, long give thought multiple-function @description.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"order-of-includes","dir":"Articles","previous_headings":"Multiple functions in the same topic","what":"Order of includes","title":"Reusing documentation","text":"default, roxygen blocks processed order appear file. ’re combining multiple files, can sometimes cause function usage appear suboptimal order. can override default ordering @order. example, following block place times first arith.Rd 1 comes 2.","code":"#' @rdname arith #' @order 2 add <- function(x, y) x + y #' @rdname arith #' @order 1 times <- function(x, y) x * y"},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"automatically-copy-tags","dir":"Articles","previous_headings":"","what":"Automatically copy tags","title":"Reusing documentation","text":"two functions share similarities different complex enough don’t want document single file, can use one four @inherit tags automatically copy various components another topic: @inheritParams foo copy @param contents foo. @inherit foo copy supported components foo. @inheritSection foo {Section title} copy @section {Section title} section foo. @inheritDotParams foo generate documentation … copying documentation foo()’s arguments. think “inheritance” rather just copying, anything inherit can overridden specific definition documentation. applies particularly @inheritParams allows copy documentation parameters documenting others directly. ’ll focus first.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"parameters","dir":"Articles","previous_headings":"Automatically copy tags","what":"Parameters","title":"Reusing documentation","text":"oldest, frequently used, inherits tag @inheritParams. ’s particularly useful multiple functions use argument name task, can document argument , inherit docs elsewhere. example, take dplyr functions arrange(), mutate(), summarise() argument called .data. arrange() documented like : mutate() summarise() don’t need provide @param .data can instead inherit documentation arrange(): wrote wouldn’t quite right mutate() summarise() also inherit documentation ..., different interpretation functions. , example, mutate() provides definition ...: Note documentation arguments names inherited. example, arrange() also .by_group argument. Since function dplyr argument name, documentation never inherited.","code":"#' @param .data A data frame, data frame extension (e.g. a tibble), or a #' lazy data frame (e.g. from dbplyr or dtplyr). See *Methods*, below, for #' more details. #' @param ... <[`data-masking`][rlang::args_data_masking]> Variables, or #' functions of variables. Use [desc()] to sort a variable in descending #' order. arrange <- function(.data, ...) {} #' @inheritParams arrange mutate <- function(.data, ...) {} #' @inheritParams arrange summarise <- function(.data, ...) {} #' @inheritParams arrange #' @param ... <[`data-masking`][rlang::args_data_masking]> Name-value pairs. #' The name gives the name of the column in the output. #' #' The value can be: #' #' * A vector of length 1, which will be recycled to the correct length. #' * A vector the same length as the current group (or the whole data frame #' if ungrouped). #' * `NULL`, to remove the column. #' * A data frame or tibble, to create multiple columns in the output. mutate <- function(.data, ...) {}"},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"multiple-parameters","dir":"Articles","previous_headings":"Automatically copy tags","what":"Multiple parameters","title":"Reusing documentation","text":"Sometimes document two () tightly coupled parameters together. example, dplyr::left_join() : joint parameter documentation inherited, ’s nothing, .e. function @inheritParams left_join inherit documentation x y x y arguments neither documented inheriting function.","code":"#' @param x,y A pair of data frames, data frame extensions (e.g. a tibble), or #' lazy data frames (e.g. from dbplyr or dtplyr). See *Methods*, below, for #' more details."},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"the-dot-prefix","dir":"Articles","previous_headings":"Automatically copy tags","what":"The dot prefix","title":"Reusing documentation","text":"Many tidyverse functions accept named arguments ... also use . prefix arguments. reduces risk argument going wrong place. example, dplyr::mutate() ., .keep, ., .arguments, didn’t prefix, wouldn’t able create new variables called , keep, , . call pattern dot prefix. means argument meaning can come one two forms: without .. @inheritParams knows common pattern ignores . prefix matching argument name. words, .x inherit documentation x, x inherit documentation .x.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"inheriting-other-components","dir":"Articles","previous_headings":"Automatically copy tags","what":"Inheriting other components","title":"Reusing documentation","text":"can use @inherits foo inherit documentation every supported tag another topic. Currently, @inherits supports inheriting following tags: params, return, title, description, details, seealso, sections, references, examples, author, source, note, format. supplying space separated list components function name, can also choose inherit selected components. example, @inherit foo returns just inherit @returns tag, @inherit foo seealso source inherit @seealso @source tags. @inherit foo sections inherit every @section tag (can also specified markdown using top-level heading spec, #). inherit specific section another function, use @inheritSection foo Section title. example, “adverbs” purrr use #' @inheritSection safely Adverbs inherit standard section provides advice using adverb package code.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"documenting----","dir":"Articles","previous_headings":"Automatically copy tags","what":"Documenting ...","title":"Reusing documentation","text":"function passes ... another function, can useful inline documentation common arguments. technique inspired documentation plot(), ... can take graphical parameter; ?plot describes common arguments don’t look ?par. @inheritDotParams two components: function inherit arguments inherit. Since ’ll typically want document important arguments, @inheritDotParams comes flexible specification argument selection inspired dplyr::select(): @inheritDotParams foo takes parameters foo(). @inheritDotParams foo b e:h takes parameters , b, parameters e h. @inheritDotParams foo -x -y takes parameters except x y.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"inheriting-from-other-packages","dir":"Articles","previous_headings":"Automatically copy tags","what":"Inheriting from other packages","title":"Reusing documentation","text":"’s common inherit documentation topics within current package, roxygen2 also supports inheriting documentation packages using package::function syntax, e.g.: @inheritParams package::function @inherit package::function @inheritSection package::function Section title @inheritDotParams package::function inheriting documentation another package bear mind ’re now taking fairly strong dependency external package, ensure every developer produces documentation ’ll need make sure version package installed. package changes name topic section, documentation require update. reasons, technique best used sparingly.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"inline-code","dir":"Articles","previous_headings":"","what":"Inline code","title":"Reusing documentation","text":"insert code inline, enclose `r `. Roxygen interpret rest text within backticks R code evaluate , replace backtick expression value. ’s simple example: equivalent writing: resulting text, together whole tag interpreted markdown, usual. means can use R dynamically write markdown. example defined function package: write: result equivalent writing following hand: powerful technique reducing duplication can flexibly parameterise function however best meets needs. Note evaluation environment deliberately child package ’re documenting can call internal functions.","code":"#' Title `r 1 + 1` #' #' Description `r 2 + 2` foo <- function() NULL #' Title 2 #' #' Description 4 foo <- function() NULL alphabet <- function(n) { paste0(\"`\", letters[1:n], \"`\", collapse = \", \") } #' Title #' #' @param x A string. Must be one of `r alphabet(5)` foo <- function(x) NULL #' Title #' #' @param x A string. Must be one of `a`, `b`, `c`, `d`, `e` foo <- function(x) NULL"},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"child-documents","dir":"Articles","previous_headings":"","what":"Child documents","title":"Reusing documentation","text":"can use .Rmd .md document documentation, README.Rmd, vignettes using child documents: included Rmd file can roxygen Markdown-style links help topics. E.g. [roxygen2::roxygenize()] link manual page roxygenize function roxygen2. See vignette(\"rd-formatting\") details. Rmd file contains roxygen (Markdown-style) links help topics, care needed, links work Rmd files default. workaround specify external HTML links . external locations used manual instead always links help topics manual. Example: example link supplied URLs HTML / Markdown files link roxygenize help topic manual. Note add external link targets like , roxygen emit warning link references defined multiple times (externally, help topic). warning originates Pandoc, harmless.","code":"```{r child = \"common.Rmd\"} ``` See also the [roxygen2::roxygenize()] function. [roxygen2::roxygenize()]: https://roxygen2.r-lib.org/reference/roxygenize.html"},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"superseded","dir":"Articles","previous_headings":"","what":"Superseded","title":"Reusing documentation","text":"years, experimented number ways reduce duplication across documentation files. number now superseded recommend changing use techniques described : Instead @includeRmd man/rmd/example.Rmd, use child document. Instead @eval @evalRd, use inline R code. Instead @template @templateVars write function call inline R code. Inline R markdown can generate markdown text within tag principle less flexible @eval/@evalRd/@template. However, experience revealed generating multiple tags tends rather inflexible, often end refactoring smaller pieces don’t believe reflects real loss functionality.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/roxygen2.html","id":"learn-more","dir":"Articles","previous_headings":"","what":"Learn more","title":"Get started with roxygen2","text":"vignette provides high-level description roxygen2 overall workflow ’ll use . vignettes provide detail important individual components: Start vignette(\"rd\") learn document functions roxygen2. vignette(\"rd-\") discusses document things like datasets, package , various pieces used R’s OOP systems. vignette(\"rd-formatting\") gives details roxygen2’s rmarkdown support. vignette(\"reuse\") demonstrates tools available reuse documentation multiple places. vignette(\"namespace\") describes generate NAMESPACE file, namespacing works R, can use roxygen2 specific package needs supplies.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/roxygen2.html","id":"running-roxygen","dir":"Articles","previous_headings":"","what":"Running roxygen","title":"Get started with roxygen2","text":"three main ways run roxygen: roxygen2::roxygenise(). devtools::document(). Ctrl + Shift + D, ’re using RStudio. can mix handwritten Rd roxygen2; roxygen2 never overwrite file didn’t create.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/roxygen2.html","id":"basic-process","dir":"Articles","previous_headings":"","what":"Basic process","title":"Get started with roxygen2","text":"three steps transformation roxygen comments source file human readable documentation: add roxygen comments source file. roxygen2::roxygenise() converts roxygen comments .Rd files. R converts .Rd files human readable documentation. process starts add specially formatted roxygen comments source file. Roxygen comments start #' can continue use regular comments purposes. example , generate man/add.Rd looks like: Rd files special file format loosely based LaTeX. can read Rd format R extensions manual. roxygen2, reasons know Rd files, ’ll avoid discussing much possible, focusing instead need know roxygen2. use ?x, help(\"x\") example(\"x\") R looks Rd file containing \\alias{x}. parses file, converts HTML displays . functions look Rd file installed packages. isn’t useful package development, want use .Rd files source package. reason, recommend use roxygen2 conjunction devtools: devtools::load_all() automatically adds shims ? friends look development package.","code":"#' Add together two numbers #' #' @param x A number. #' @param y A number. #' @return A number. #' @examples #' add(1, 1) #' add(10, 1) add <- function(x, y) { x + y } % Generated by roxygen2: do not edit by hand % Please edit documentation in ./ \\name{add} \\alias{add} \\title{Add together two numbers} \\usage{ add(x, y) } \\arguments{ \\item{x}{A number.} \\item{y}{A number.} } \\value{ A number. } \\description{ Add together two numbers } \\examples{ add(1, 1) add(10, 1) }"},{"path":"https://roxygen2.r-lib.org/dev/authors.html","id":null,"dir":"","previous_headings":"","what":"Authors","title":"Authors and Citation","text":"Hadley Wickham. Author, maintainer, copyright holder. Peter Danenberg. Author, copyright holder. Gábor Csárdi. Author. Manuel Eugster. Author, copyright holder. . Copyright holder, funder.","code":""},{"path":"https://roxygen2.r-lib.org/dev/authors.html","id":"citation","dir":"","previous_headings":"","what":"Citation","title":"Authors and Citation","text":"Wickham H, Danenberg P, Csárdi G, Eugster M (2024). roxygen2: -Line Documentation R. R package version 7.3.0.9000, https://github.com/r-lib/roxygen2, https://roxygen2.r-lib.org/.","code":"@Manual{, title = {roxygen2: In-Line Documentation for R}, author = {Hadley Wickham and Peter Danenberg and Gábor Csárdi and Manuel Eugster}, year = {2024}, note = {R package version 7.3.0.9000, https://github.com/r-lib/roxygen2}, url = {https://roxygen2.r-lib.org/}, }"},{"path":"https://roxygen2.r-lib.org/dev/index.html","id":"roxygen2-","dir":"","previous_headings":"","what":"In-Line Documentation for R","title":"In-Line Documentation for R","text":"premise roxygen2 simple: describe functions comments next definitions roxygen2 process source code comments automatically generate .Rd files man/, NAMESPACE, , needed, Collate field DESCRIPTION.","code":""},{"path":"https://roxygen2.r-lib.org/dev/index.html","id":"installation","dir":"","previous_headings":"","what":"Installation","title":"In-Line Documentation for R","text":"","code":"# Install roxygen2 from CRAN install.packages(\"roxygen2\") # Or the development version from GitHub: # install.packages(\"pak\") pak::pak(\"r-lib/roxygen2\")"},{"path":"https://roxygen2.r-lib.org/dev/index.html","id":"usage","dir":"","previous_headings":"","what":"Usage","title":"In-Line Documentation for R","text":"premise roxygen2 simple: describe functions comments next definitions roxygen2 process source code comments produce Rd files man/ directory. ’s simple example stringr package: roxygenise() (devtools::document()) package comments automatically transformed .Rd R uses generate documentation see type ?str_length.","code":"#' The length of a string #' #' Technically this returns the number of \"code points\", in a string. One #' code point usually corresponds to one character, but not always. For example, #' an u with a umlaut might be represented as a single character or as the #' combination a u and an umlaut. #' #' @inheritParams str_detect #' @return A numeric vector giving number of characters (code points) in each #' element of the character vector. Missing string have missing length. #' @seealso [stringi::stri_length()] which this function wraps. #' @export #' @examples #' str_length(letters) #' str_length(NA) #' str_length(factor(\"abc\")) #' str_length(c(\"i\", \"like\", \"programming\", NA)) str_length <- function(string) { }"},{"path":"https://roxygen2.r-lib.org/dev/index.html","id":"learn-more","dir":"","previous_headings":"","what":"Learn more","title":"In-Line Documentation for R","text":"get started, first read vignette(\"roxygen2\"). read specific package component want generate: Start vignette(\"rd\") learn document functions roxygen2. vignette(\"rd-\") discusses document things like datasets, package , various pieces used R’s OOP systems. vignette(\"rd-formatting\") gives details roxygen2’s rmarkdown support. vignette(\"reuse\") demonstrates tools available reuse documentation multiple places. vignette(\"namespace\") describes generate NAMESPACE file, namespacing works R, can use roxygen2 specific package needs supplies. Collate field DESCRIPTION, see ?update_collate().","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":null,"dir":"Reference","previous_headings":"","what":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"RoxyTopic object corresponds generated .Rd file.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"public-fields","dir":"Reference","previous_headings":"","what":"Public fields","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"sections Named list sections. item must rd_section() object. filename Path .Rd file generate.","code":""},{"path":[]},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"public-methods","dir":"Reference","previous_headings":"","what":"Public methods","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"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()","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"method-format-","dir":"Reference","previous_headings":"","what":"Method format()","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Format .Rd file. considers sections particular order, even though Rd tools reorder .","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"usage","dir":"Reference","previous_headings":"","what":"Usage","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"","code":"RoxyTopic$format(...)"},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"... Passed format() methods rd_section() objects, sections.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"returns","dir":"Reference","previous_headings":"","what":"Returns","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Character string.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"method-is-valid-","dir":"Reference","previous_headings":"","what":"Method is_valid()","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Check .Rd file valid","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"usage-1","dir":"Reference","previous_headings":"","what":"Usage","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"","code":"RoxyTopic$is_valid()"},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"returns-1","dir":"Reference","previous_headings":"","what":"Returns","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Logical flag, TRUE valid .Rd files","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"method-has-section-","dir":"Reference","previous_headings":"","what":"Method has_section()","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Check .Rd file certain section.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"usage-2","dir":"Reference","previous_headings":"","what":"Usage","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"","code":"RoxyTopic$has_section(type)"},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"arguments-1","dir":"Reference","previous_headings":"","what":"Arguments","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"type Section type, character scalar.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"returns-2","dir":"Reference","previous_headings":"","what":"Returns","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Logical flag.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"method-get-section-","dir":"Reference","previous_headings":"","what":"Method get_section()","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Query section.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"usage-3","dir":"Reference","previous_headings":"","what":"Usage","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"","code":"RoxyTopic$get_section(type)"},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"arguments-2","dir":"Reference","previous_headings":"","what":"Arguments","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"type Section type, character scalar.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"returns-3","dir":"Reference","previous_headings":"","what":"Returns","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"rd_section object representing section, NULL topic section.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"method-get-value-","dir":"Reference","previous_headings":"","what":"Method get_value()","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Query value section. value rd_section object.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"usage-4","dir":"Reference","previous_headings":"","what":"Usage","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"","code":"RoxyTopic$get_value(type)"},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"arguments-3","dir":"Reference","previous_headings":"","what":"Arguments","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"type Section type, character scalar.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"returns-4","dir":"Reference","previous_headings":"","what":"Returns","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Value.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"method-get-rd-","dir":"Reference","previous_headings":"","what":"Method get_rd()","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Get Rd code section.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"usage-5","dir":"Reference","previous_headings":"","what":"Usage","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"","code":"RoxyTopic$get_rd(type)"},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"arguments-4","dir":"Reference","previous_headings":"","what":"Arguments","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"type Section type, character scalar.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"returns-5","dir":"Reference","previous_headings":"","what":"Returns","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Character vector, one element per line.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"method-get-name-","dir":"Reference","previous_headings":"","what":"Method get_name()","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Get value name section. name Rd topic.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"usage-6","dir":"Reference","previous_headings":"","what":"Usage","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"","code":"RoxyTopic$get_name()"},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"returns-6","dir":"Reference","previous_headings":"","what":"Returns","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Character scalar.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"method-inherits-from-","dir":"Reference","previous_headings":"","what":"Method inherits_from()","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Query topics topic inherits type .","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"usage-7","dir":"Reference","previous_headings":"","what":"Usage","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"","code":"RoxyTopic$inherits_from(type)"},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"arguments-5","dir":"Reference","previous_headings":"","what":"Arguments","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"type Section type, character scalar.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"returns-7","dir":"Reference","previous_headings":"","what":"Returns","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"character vector topic names.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"method-inherits-section-from-","dir":"Reference","previous_headings":"","what":"Method inherits_section_from()","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Query topics topic inherits sections .","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"usage-8","dir":"Reference","previous_headings":"","what":"Usage","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"","code":"RoxyTopic$inherits_section_from()"},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"returns-8","dir":"Reference","previous_headings":"","what":"Returns","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"character vector topic names.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"method-add-","dir":"Reference","previous_headings":"","what":"Method add()","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Add one sections topic.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"usage-9","dir":"Reference","previous_headings":"","what":"Usage","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"","code":"RoxyTopic$add(x, block = \"???\", overwrite = FALSE)"},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"arguments-6","dir":"Reference","previous_headings":"","what":"Arguments","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"x Section(s) add. may another RoxyTopic object, sections added; rd_section object; list rd_section objects add. block Name block use error messages. overwrite Whether overwrite existing section. FALSE two sections merged.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"method-add-section-","dir":"Reference","previous_headings":"","what":"Method add_section()","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Add section.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"usage-10","dir":"Reference","previous_headings":"","what":"Usage","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"","code":"RoxyTopic$add_section(section, block = \"???\", overwrite = FALSE)"},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"arguments-7","dir":"Reference","previous_headings":"","what":"Arguments","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"section rd_section object add. block Name block use error messages. overwrite Whether overwrite existing section. FALSE two sections merged.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Ensures type name (given name), appears self$sections. method internal use .","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"method-clone-","dir":"Reference","previous_headings":"","what":"Method clone()","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"objects class cloneable method.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"usage-11","dir":"Reference","previous_headings":"","what":"Usage","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"","code":"RoxyTopic$clone(deep = FALSE)"},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"arguments-8","dir":"Reference","previous_headings":"","what":"Arguments","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"deep Whether make deep clone.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/double_escape_md.html","id":null,"dir":"Reference","previous_headings":"","what":"Check markdown escaping — double_escape_md","title":"Check markdown escaping — double_escape_md","text":"regression test Markdown escaping.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/double_escape_md.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Check markdown escaping — double_escape_md","text":"","code":"double_escape_md(text)"},{"path":"https://roxygen2.r-lib.org/dev/reference/double_escape_md.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Check markdown escaping — double_escape_md","text":"text Input text.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/double_escape_md.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Check markdown escaping — double_escape_md","text":"Double-escaped text.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/double_escape_md.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Check markdown escaping — double_escape_md","text":"following bullets look rendered: Backticks: \\, \\%, \\$, \\_ \\verb{}: \\, \\%, \\$, \\_ [ link ] \\[ neither \\]","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/double_escape_md.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Check markdown escaping — double_escape_md","text":"","code":"\"%\" # percent #> [1] \"%\" \"\\\"\" # double quote #> [1] \"\\\"\" '\\'' # single quote #> [1] \"'\""},{"path":"https://roxygen2.r-lib.org/dev/reference/escape_examples.html","id":null,"dir":"Reference","previous_headings":"","what":"Escape examples — escape_examples","title":"Escape examples — escape_examples","text":"documentation topic used primarily testing record understanding \\example{} escaping rules. See https://developer.r-project.org/parseRd.pdf details provided R core.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/escape_examples.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Escape examples — escape_examples","text":"","code":"escape_examples(x)"},{"path":"https://roxygen2.r-lib.org/dev/reference/escape_examples.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Escape examples — escape_examples","text":"","code":"# In examples we automatically escape Rd comments (%): 100 %% 30 #> [1] 10 # even if they are in strings \"50%\" #> [1] \"50%\" # and \\ and \\v inside of strings and symbols \"\\v\" # vertical tab #> [1] \"\\v\" \"\\\\\" #> [1] \"\\\\\" # but not comments: \\l \\v # other string escapes are left as is \"\\\"\" #> [1] \"\\\"\" \"\\n\" #> [1] \"\\n\" # Otherwise, backslashes and parentheses are left as is. This # means that you need to escape unbalanced parentheses, which typically only # occur in \\dontshow{}: if (FALSE) { print(\"Hello\") } # You also need to escape backslashes in infix operators and comments # (this is generally rare) `%\\\\%` <- function(x, y) x + y 10 %\\% 20 #> [1] 30 # \\\\ (renders as two backslashes)"},{"path":"https://roxygen2.r-lib.org/dev/reference/is_s3_generic.html","id":null,"dir":"Reference","previous_headings":"","what":"Determine if a function is an S3 generic or S3 method. — is_s3_generic","title":"Determine if a function is an S3 generic or S3 method. — is_s3_generic","text":"is_s3_generic compares name .knownS3Generics .S3PrimitiveGenerics, looks function body see calls UseMethod(). is_s3_method builds names possible generics function checks actually generic.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/is_s3_generic.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Determine if a function is an S3 generic or S3 method. — is_s3_generic","text":"","code":"is_s3_generic(name, env = parent.frame()) is_s3_method(name, env = parent.frame())"},{"path":"https://roxygen2.r-lib.org/dev/reference/is_s3_generic.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Determine if a function is an S3 generic or S3 method. — is_s3_generic","text":"name Name function. env Base environment look function definition.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/load.html","id":null,"dir":"Reference","previous_headings":"","what":"Load package code — load","title":"Load package code — load","text":"roxygen2 dynamic documentation system, means works objects inside package, just source code used create . functions offer various ways loading package suit various constraints: load_pkgload() uses pkgload::load_all() simulate package loading closely know . offers high fidelity handling code uses S4, requires package compiled. load_source() simulates package loading attaching packages listed Depends Imports, sources files R/ directory. default strategy used roxygen2 6.0.0 earlier; primary advantage need compilation. load_installed() uses installed version package. Use strategy installed development version package already. highest fidelity strategy, requires work outside roxygen2. can change default strategy function roxygen2 load option. Override default pkgload use source installed strategies:","code":"Roxygen: list(load = \"source\")"},{"path":"https://roxygen2.r-lib.org/dev/reference/load.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Load package code — load","text":"","code":"load_pkgload(path) load_installed(path) load_source(path)"},{"path":"https://roxygen2.r-lib.org/dev/reference/load.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Load package code — load","text":"path Path source package","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/load_options.html","id":null,"dir":"Reference","previous_headings":"","what":"Load roxygen2 options — load_options","title":"Load roxygen2 options — load_options","text":"Options can stored Roxygen field DESCRIPTION, man/roxygen/meta.R. either case, code parsed evaluated child base environment. Call roxy_meta_get() access current option values within tag roclet methods. Options man/roxygen/meta.R override present DESCRIPTION.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/load_options.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Load roxygen2 options — load_options","text":"","code":"load_options(base_path = \".\") roxy_meta_get(key = NULL, default = NULL)"},{"path":"https://roxygen2.r-lib.org/dev/reference/load_options.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Load roxygen2 options — load_options","text":"base_path Path package.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/load_options.html","id":"possible-options","dir":"Reference","previous_headings":"","what":"Possible options","title":"Load roxygen2 options — load_options","text":"roclets : giving names roclets run. See roclet_find() details. packages : packages load implement new tags. load : load R code. See load details. old_usage : use old style usage formatting? markdown : translate markdown syntax Rd? r6 : document R6 classes? current_package (read ): name package documented. rd_family_title : overrides @family titles. See rd vignette details: vignette(\"rd\", package = \"roxygen2\") knitr_chunk_options : default chunk options used knitr. restrict_image_formats : TRUE PDF images included PDF manual, SVG images included HTML manual. (applies images supplied via markdown.)","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/load_options.html","id":"how-to-set","dir":"Reference","previous_headings":"","what":"How to set","title":"Load roxygen2 options — load_options","text":"Either set DESCRIPTION: longer, can put /man/roxygen/meta.R:","code":"Roxygen: list(markdown = TRUE, load = \"installed\") list( markdown = TRUE, load = \"installed\" )"},{"path":"https://roxygen2.r-lib.org/dev/reference/markdown-internals.html","id":null,"dir":"Reference","previous_headings":"","what":"Escape Rd markup, to avoid interpreting it as markdown — escape_rd_for_md","title":"Escape Rd markup, to avoid interpreting it as markdown — escape_rd_for_md","text":"needed, want stay compatible existing markup, even markdown mode switched . Fragile Rd tags (tags may contain markup can picked markdown parser), replaced placeholders. markdown Rd conversion done, original text put back place placeholders. puts back protected fragile Rd commands text markdown parsing.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/markdown-internals.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Escape Rd markup, to avoid interpreting it as markdown — escape_rd_for_md","text":"","code":"escape_rd_for_md(text) unescape_rd_for_md(rd_text, esc_text)"},{"path":"https://roxygen2.r-lib.org/dev/reference/markdown-internals.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Escape Rd markup, to avoid interpreting it as markdown — escape_rd_for_md","text":"text Input text. Potentially contains Rd /markdown markup. rd_text markdown parsed interpreted text. esc_text original escaped text escape_rd_for_md().","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/markdown-internals.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Escape Rd markup, to avoid interpreting it as markdown — escape_rd_for_md","text":"escape_rd_for_md: “safe” version input text, fragile Rd tag replaced placeholder. original text added attribute placeholder. unescape_rd_for_md: Rd text.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/markdown-internals.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Escape Rd markup, to avoid interpreting it as markdown — escape_rd_for_md","text":"list protected Rd tags escaped_for_md. Rd macros treated specially: , markdown allowed second argument. ifelse markdown allowed second third arguments. See also roclet-rd.R list tags uses markdown-enabled parser. tags, e.g. @aliases, @backref, etc. use standard Roxygen parser.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/markdown-test.html","id":null,"dir":"Reference","previous_headings":"","what":"Dummy page to test roxygen's markdown formatting — markdown-test","title":"Dummy page to test roxygen's markdown formatting — markdown-test","text":"Links tricky, put links : Link function: roxygenize(). Link object: roxygenize (just treat like object .","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/markdown-test.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Dummy page to test roxygen's markdown formatting — markdown-test","text":"Link another package, function: desc::desc(). Link another package, non-function: desc::desc. Link link text: great function, roxygenize, great function. another package: one. table:","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/markdown_pass1.html","id":null,"dir":"Reference","previous_headings":"","what":"Expand the embedded inline code — markdown_pass1","title":"Expand the embedded inline code — markdown_pass1","text":"Expand embedded inline code","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/markdown_pass1.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Expand the embedded inline code — markdown_pass1","text":"","code":"markdown_pass1(text)"},{"path":"https://roxygen2.r-lib.org/dev/reference/markdown_pass1.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Expand the embedded inline code — markdown_pass1","text":"text Input text.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/markdown_pass1.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Expand the embedded inline code — markdown_pass1","text":"Text R code expanded. character vector length input text.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/markdown_pass1.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Expand the embedded inline code — markdown_pass1","text":"example becomes two: 2. Variables can set reused, within tag: value x 100. access internal functions package, e.g. since roxygen2, can refer internal markdown function, TRUE: TRUE. insert name current package: roxygen2. iris data set 5 columns: Sepal.Length, Sepal.Width, Petal.Length, Petal.Width, Species. Chunk options: Plots: Alternative knitr engines: Also see vignette(\"rd-formatting\").","code":"# Code block demo x + 1 #> [1] 101 names(mtcars) nrow(mtcars) #> [1] \"mpg\" \"cyl\" \"disp\" \"hp\" \"drat\" \"wt\" \"qsec\" \"vs\" \"am\" \"gear\" #> [11] \"carb\" #> [1] 32 plot(1:10) ```{r} # comment this <- 10 is <- this + 10 good <- this + is"},{"path":"https://roxygen2.r-lib.org/dev/reference/namespace_roclet.html","id":null,"dir":"Reference","previous_headings":"","what":"Roclet: make NAMESPACE — namespace_roclet","title":"Roclet: make NAMESPACE — namespace_roclet","text":"roclet automates production NAMESPACE file, controls functions imported exported package, described Writing R extensions. NAMESPACE generated two passes: first generates import directives (can computed without evaluating package code), second generates everything (package loaded). See vignette(\"namespace\") details.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/namespace_roclet.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Roclet: make NAMESPACE — namespace_roclet","text":"","code":"namespace_roclet()"},{"path":[]},{"path":"https://roxygen2.r-lib.org/dev/reference/namespace_roclet.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Roclet: make NAMESPACE — namespace_roclet","text":"","code":"# 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 #> NULL"},{"path":"https://roxygen2.r-lib.org/dev/reference/object.html","id":null,"dir":"Reference","previous_headings":"","what":"Constructors for S3 object to represent R objects. — object","title":"Constructors for S3 object to represent R objects. — object","text":"objects usually created parsers, also useful generate hand testing.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/object.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Constructors for S3 object to represent R objects. — object","text":"","code":"object(value, alias, type)"},{"path":"https://roxygen2.r-lib.org/dev/reference/object.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Constructors for S3 object to represent R objects. — object","text":"value object . alias Alias object documented, case create generator function different name.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/object_format.html","id":null,"dir":"Reference","previous_headings":"","what":"Default format for data — object_format","title":"Default format for data — object_format","text":"function called generate default \"Format\" section data object. default implementation return class dimension information.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/object_format.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Default format for data — object_format","text":"","code":"object_format(x)"},{"path":"https://roxygen2.r-lib.org/dev/reference/object_format.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Default format for data — object_format","text":"x data object","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/object_format.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Default format for data — object_format","text":"character value valid Rd syntax, NULL.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/parse_package.html","id":null,"dir":"Reference","previous_headings":"","what":"Parse a package, file, or inline code — parse_package","title":"Parse a package, file, or inline code — parse_package","text":"parse_package(), parse_file(), parse_text() allow use roxygen's parsing code parse roxygen blocks package, file, character vector code. env_package() env_file() provide defaults generate temporary environment making possible associate block corresponding live object.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/parse_package.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Parse a package, file, or inline code — parse_package","text":"","code":"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)"},{"path":"https://roxygen2.r-lib.org/dev/reference/parse_package.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Parse a package, file, or inline code — parse_package","text":"path, file, text Either specify path root directory package, R file, character vector text. env environment environment containing result evaluating input code. defaults test environment: real code need generate environment . can also set NULL want get tokenized code blocks . suppresses evaluation @eval tags, find code object associated block.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/parse_package.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Parse a package, file, or inline code — parse_package","text":"list roxy_block objects","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/rd_roclet.html","id":null,"dir":"Reference","previous_headings":"","what":"Roclet: make Rd files — rd_roclet","title":"Roclet: make Rd files — rd_roclet","text":"roclet workhorse roxygen2, producing .Rd files R uses document functions, datasets, packages, classes, . See vignette(\"rd\") details. Generally call function directly instead use roxygenise() specifying rd roclet.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/rd_roclet.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Roclet: make Rd files — rd_roclet","text":"","code":"rd_roclet()"},{"path":[]},{"path":"https://roxygen2.r-lib.org/dev/reference/rd_roclet.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Roclet: make Rd files — rd_roclet","text":"","code":"#' 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) { }"},{"path":"https://roxygen2.r-lib.org/dev/reference/rd_section.html","id":null,"dir":"Reference","previous_headings":"","what":"Construct an rd_section object — rd_section","title":"Construct an rd_section object — rd_section","text":"rd_section represents Rd command can appear top-level Rd document, like \\name{}, \\title{}, \\description{}, \\section{}.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/rd_section.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Construct an rd_section object — rd_section","text":"","code":"rd_section(type, value)"},{"path":"https://roxygen2.r-lib.org/dev/reference/rd_section.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Construct an rd_section object — rd_section","text":"type Section type. Stored type field, class rd_section_{type}. avoid namespace clashes different extensions, include package name. value Section data. used format() merge() methods.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/rd_section.html","id":"methods","dir":"Reference","previous_headings":"","what":"Methods","title":"Construct an rd_section object — rd_section","text":"provide rd_section type, also need define format.rd_section_{type} method returns formatted Rd output. may also need provide merge.rd_section_{type} method two sections can combined rd_section(x$type, c(x$value, y$value)). See vignette(\"extending\") details.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roc_proc_text.html","id":null,"dir":"Reference","previous_headings":"","what":"Process roclet on string and capture results. — roc_proc_text","title":"Process roclet on string and capture results. — roc_proc_text","text":"Useful testing.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roc_proc_text.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Process roclet on string and capture results. — roc_proc_text","text":"","code":"roc_proc_text(roclet, input, wd = NULL)"},{"path":"https://roxygen2.r-lib.org/dev/reference/roc_proc_text.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Process roclet on string and capture results. — roc_proc_text","text":"roclet Name roclet use processing. input Source string wd Working directory","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roclet.html","id":null,"dir":"Reference","previous_headings":"","what":"Build a new roclet. — roclet","title":"Build a new roclet. — roclet","text":"create new roclet, need create constructor function wraps roclet, implement methods described .","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roclet.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Build a new roclet. — roclet","text":"","code":"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)"},{"path":"https://roxygen2.r-lib.org/dev/reference/roclet.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Build a new roclet. — roclet","text":"x roclet object. blocks list roxy_block objects. base_path Path root source package. env Package environment. results Value returned roclet_process() method.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roclet.html","id":"methods","dir":"Reference","previous_headings":"","what":"Methods","title":"Build a new roclet. — roclet","text":"roclet_preprocess() called blocks parsed code evaluated. needed roclet affects code evaluated. return roclet. roclet_process() called blocks evaluated; .e. @eval tag processed, object associated block determined. roclet_output() given output roclet_process() produce files disk. roclet_clean() called roxygenise(clean = TRUE). remove files created roclet.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roclet.html","id":"deprecated-methods","dir":"Reference","previous_headings":"","what":"Deprecated methods","title":"Build a new roclet. — roclet","text":"roclet_tags() longer used; instead provide roxy_tag_parse() method tag.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roclet_find.html","id":null,"dir":"Reference","previous_headings":"","what":"Create a roclet from a string. — roclet_find","title":"Create a roclet from a string. — roclet_find","text":"provides flexible way specifying roclet string.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roclet_find.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create a roclet from a string. — roclet_find","text":"","code":"roclet_find(x)"},{"path":"https://roxygen2.r-lib.org/dev/reference/roclet_find.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create a roclet from a string. — roclet_find","text":"x Arbitrary R code evaluated roxygen2 package.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roclet_find.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create a roclet from a string. — roclet_find","text":"","code":"# rd, namespace, and vignette work for backward compatibility roclet_find(\"rd\") #> list() #> attr(,\"class\") #> [1] \"roclet_rd\" \"roclet\" # But generally you should specify the name of a function that # returns a roclet roclet_find(\"rd_roclet\") #> list() #> attr(,\"class\") #> [1] \"roclet_rd\" \"roclet\" # If it lives in another package, you'll need to use :: roclet_find(\"roxygen2::rd_roclet\") #> list() #> attr(,\"class\") #> [1] \"roclet_rd\" \"roclet\" # If it takes parameters (which no roclet does currently), you'll need # to call the function roclet_find(\"roxygen2::rd_roclet()\") #> list() #> attr(,\"class\") #> [1] \"roclet_rd\" \"roclet\""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxy_block.html","id":null,"dir":"Reference","previous_headings":"","what":"Blocks — roxy_block","title":"Blocks — roxy_block","text":"roxy_block represents single roxygen2 block. block_* functions provide helpers common operations: block_has_tag(blocks, tags): block contain tags? block_get_tags(block, tags): get instances tags block_get_tag(block, tag): get single tag. Returns NULL 0, throws warning 1. block_get_tag_value(block, tag): gets val field single tag.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxy_block.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Blocks — roxy_block","text":"","code":"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)"},{"path":"https://roxygen2.r-lib.org/dev/reference/roxy_block.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Blocks — roxy_block","text":"tags list roxy_tags. file, line Location call (.e. line last line block). call Expression associated block. object Optionally, object associated block, found inspecting/evaluating call. block roxy_block manipulate. tag single tag name.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxy_block.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Blocks — roxy_block","text":"","code":"# 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 #> [:6] #> $tag #> [line: 2] @title 'This is a title' {parsed} #> [line: 4] @param 'x,y A number' {parsed} #> [line: 5] @export '' {parsed} #> [line: 6] @usage '' {parsed} #> [line: 6] @.formals '' {parsed} #> [line: 6] @backref '' {parsed} #> $call f <- function(x, y) x + y #> $object #> $topic f #> $alias f"},{"path":"https://roxygen2.r-lib.org/dev/reference/roxy_tag.html","id":null,"dir":"Reference","previous_headings":"","what":"roxy_tag S3 constructor — roxy_tag","title":"roxy_tag S3 constructor — roxy_tag","text":"roxy_tag() constructor tag objects. roxy_tag_warning() superseded warn_roxy_tag(); use generate warning includes location tag.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxy_tag.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"roxy_tag S3 constructor — roxy_tag","text":"","code":"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())"},{"path":"https://roxygen2.r-lib.org/dev/reference/roxy_tag.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"roxy_tag S3 constructor — roxy_tag","text":"tag Tag name. Arguments starting . reserved internal usage. raw Raw tag value, string. val Parsed tag value, typically character vector, sometimes list. Usually filled tag_parsers file, line Location tag x tag","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxy_tag.html","id":"methods","dir":"Reference","previous_headings":"","what":"Methods","title":"roxy_tag S3 constructor — roxy_tag","text":"Define method roxy_tag_parse support new tags. See tag_parsers details.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxy_tag_rd.html","id":null,"dir":"Reference","previous_headings":"","what":"Generate Rd output from a tag — roxy_tag_rd","title":"Generate Rd output from a tag — roxy_tag_rd","text":"Provide method generic want tag generate output .Rd files. See vignette(\"extending\") details.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxy_tag_rd.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Generate Rd output from a tag — roxy_tag_rd","text":"","code":"roxy_tag_rd(x, base_path, env)"},{"path":"https://roxygen2.r-lib.org/dev/reference/roxy_tag_rd.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Generate Rd output from a tag — roxy_tag_rd","text":"x tag base_path Path package root directory. env Environment evaluate code (needed)","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxy_tag_rd.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Generate Rd output from a tag — roxy_tag_rd","text":"Methods must return rd_section.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxygen2-package.html","id":null,"dir":"Reference","previous_headings":"","what":"roxygen2: In-Line Documentation for R — roxygen2-package","title":"roxygen2: In-Line Documentation for R — roxygen2-package","text":"Generate Rd documentation, 'NAMESPACE' file, collation field using specially formatted comments. Writing documentation -line code makes easier keep documentation --date requirements change. 'roxygen2' inspired 'Doxygen' system C++.","code":""},{"path":[]},{"path":"https://roxygen2.r-lib.org/dev/reference/roxygen2-package.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"roxygen2: In-Line Documentation for R — roxygen2-package","text":"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] contributors: Posit Software, PBC [copyright holder, funder]","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxygenize.html","id":null,"dir":"Reference","previous_headings":"","what":"Process a package with the Rd, namespace and collate roclets — roxygenize","title":"Process a package with the Rd, namespace and collate roclets — roxygenize","text":"workhorse function uses roclets, built-document transformation functions, build documentation package. See documentation individual roclets, rd_roclet(), namespace_roclet(), update_collate(), details.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxygenize.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Process a package with the Rd, namespace and collate roclets — roxygenize","text":"","code":"roxygenize(package.dir = \".\", roclets = NULL, load_code = NULL, clean = FALSE) roxygenise(package.dir = \".\", roclets = NULL, load_code = NULL, clean = FALSE)"},{"path":"https://roxygen2.r-lib.org/dev/reference/roxygenize.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Process a package with the Rd, namespace and collate roclets — roxygenize","text":"package.dir Location package top level directory. Default working directory. roclets Character vector roclet names use package. default, NULL, uses roxygen roclets option, defaults c(\"collate\", \"namespace\", \"rd\"). load_code function used load R code package directory. default, NULL, uses strategy defined load roxygen option, defaults load_pkgload(). See load details. clean TRUE, roxygen delete files previously created roxygen running roclet.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxygenize.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Process a package with the Rd, namespace and collate roclets — roxygenize","text":"NULL","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxygenize.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Process a package with the Rd, namespace and collate roclets — roxygenize","text":"Note roxygen2 dynamic documentation system: works inspecting loaded objects package. means must able load package order document : see load details.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/tag_parsers.html","id":null,"dir":"Reference","previous_headings":"","what":"Parse tags — tag_parsers","title":"Parse tags — tag_parsers","text":"functions parse raw tag value, convert string richer R object storing val, provide informative warning returning NULL.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/tag_parsers.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Parse tags — tag_parsers","text":"","code":"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)"},{"path":"https://roxygen2.r-lib.org/dev/reference/tag_parsers.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Parse tags — tag_parsers","text":"x roxy_tag object parse first, second Name first second parts two part tags required second part required (TRUE) can blank (FALSE)? markdown second part parsed markdown? min, max Minimum maximum number words","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/tag_parsers.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Parse tags — tag_parsers","text":"roxy_tag object val field set parsed value.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/tag_parsers.html","id":"new-tag","dir":"Reference","previous_headings":"","what":"New tag","title":"Parse tags — tag_parsers","text":"create new @mytag define roxy_tag_parse.roxy_tag_mytag(). either call one functions , directly set x$val.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/tags-index-crossref.html","id":null,"dir":"Reference","previous_headings":"","what":"Tags for indexing and cross-references — tags-index-crossref","title":"Tags for indexing and cross-references — tags-index-crossref","text":"Learn full details vignette('index-crossref'). Key tags: @aliases ${1:alias}: Add additional aliases topic. Use NULL suppress default alias automatically generated roxygen2. @concept ${1:concept}: Add additional keywords phrases included help.search() index. @concept single term phrase. @family ${1:family name}: Generate @seealso entries functions family name. @keywords ${1:keyword}: Add standardised keyword, indexed help.search(). generally useful apart @keywords internal flags topic internal removes topic indexes. @references ${1:reference}: Pointers related literature. Usually formatted like bibliography. @seealso [${1:func}()]: Link related functions urls. Usually sentence two, bulleted list. less frequently used tags: @backref ${1:path}: Manually override backreference points .Rd file back source .R file. needed generating code.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/tags-index-crossref.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Tags for indexing and cross-references — tags-index-crossref","text":"","code":"#' @aliases ${1:alias} #' @backref ${1:path} #' @concept ${1:concept} #' @family ${1:family name} #' @keywords ${1:keyword} #' @references ${1:reference} #' @seealso [${1:func}()]"},{"path":[]},{"path":"https://roxygen2.r-lib.org/dev/reference/tags-namespace.html","id":null,"dir":"Reference","previous_headings":"","what":"Tags for managing the NAMESPACE — tags-namespace","title":"Tags for managing the NAMESPACE — tags-namespace","text":"Learn full details vignette('namespace'). Key tags: @export: Export function, method, generic, class available outside package. @exportS3Method ${1:package}::${2:generic}: Export S3 method. needed method generic suggested package. @importFrom ${1:package} ${2:function}: Import specific functions package. @useDynLib ${1:package}: Import compiled code another package. less frequently used tags: @evalNamespace ${1:r-code}: Evaluate arbitrary code package namespace insert results NAMESPACE. return character vector directives. @exportClass ${1:class}: Export S4 class. expert use ; cases use @export roxygen2 can automatically generate correct directive. @exportMethod ${1:generic}: Export S4 methods. expert use ; cases use @export roxygen2 can automatically generate correct directive. @exportPattern ${1:pattern}: Export objects matching regular expression. @import ${1:package}: Import functions package. Use extreme care. @importClassesFrom ${1:package} ${2:class}: Import S4 classes another package. @importMethodsFrom ${1:package} ${2:generic}: Import S4 methods package. @rawNamespace ${1:namespace directives}: Insert literal text directly NAMESPACE.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/tags-namespace.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Tags for managing the NAMESPACE — tags-namespace","text":"","code":"#' @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}"},{"path":"https://roxygen2.r-lib.org/dev/reference/tags-rd-formatting.html","id":null,"dir":"Reference","previous_headings":"","what":"Tags related to markdown support — tags-rd-formatting","title":"Tags related to markdown support — tags-rd-formatting","text":"Learn full details vignette('rd-formatting'). less frequently used tags: @md: Force markdown processing block. @noMd: Suppress markdown processing block. @section ${1:section title}: : Add arbitrary section documentation. Now generally superseded favour using level 1 heading.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/tags-rd-formatting.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Tags related to markdown support — tags-rd-formatting","text":"","code":"#' @md #' @noMd #' @section ${1:section title}:"},{"path":"https://roxygen2.r-lib.org/dev/reference/tags-rd-other.html","id":null,"dir":"Reference","previous_headings":"","what":"Tags for documenting datasets and classes — tags-rd-other","title":"Tags for documenting datasets and classes — tags-rd-other","text":"Learn full details vignette('rd-'). Key tags: @field ${1:name} ${2:description}: Describe R6 refClass field. @format ${1:description}: Describe type/shape dataset. dataset data frame, include description column. supplied, automatically generated object_format(). @method ${1:generic} ${2:class}: Force function recognised S3 method. affects default usage NAMESPACE directive produced @export. needed automatic detection fails. @slot ${1:name} ${2:description}: Describe slot S4 class. @source ${1:description}: Describe dataset came . Provide link original source (possible) briefly describe manipulation performed importing data.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/tags-rd-other.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Tags for documenting datasets and classes — tags-rd-other","text":"","code":"#' @field ${1:name} ${2:description} #' @format ${1:description} #' @method ${1:generic} ${2:class} #' @slot ${1:name} ${2:description} #' @source ${1:description}"},{"path":[]},{"path":"https://roxygen2.r-lib.org/dev/reference/tags-rd.html","id":null,"dir":"Reference","previous_headings":"","what":"Tags for documenting functions — tags-rd","title":"Tags for documenting functions — tags-rd","text":"Learn full details vignette('rd'). Key tags: @description${1:short description...} : short description purpose function. Usually around paragraph, can longer needed. @example ${1:path}.R: Embed examples stored another file. @examples${1:# example code} : Executable R code demonstrates function works. Code must run without error. @examplesIf ${1:condition}${2:# example code} : Run examples condition TRUE. @noRd: Suppress .Rd generation block. Use documentation blocks visible source code. @param ${1:name} ${2:description}: Describe function input. describe acceptable input types affects output. description usually one two sentences can long needed. Document multiple arguments separating names commas without spaces. @returns ${1:description}: Describe function's output. Typically 1-2 sentence description output type, might also include discussion important errors warnings. @title ${1:title}: one-line description function shown various indexes. explicit @title usually needed default taken first paragraph roxygen block. @usage ${1:fun}(${2:arg1, arg2 = default, ...}): Override default usage generated roxygen2. needed roxygen2 fails correctly derive usage function. less frequently used tags: @details${1:Additional details...} : Additional details function. Generally superseded instead using level 1 heading. @rawRd ${1:rd}: Insert literal text directly .Rd file. @return ${1:description}: Describe function's output. Superseded favour @returns.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/tags-rd.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Tags for documenting functions — tags-rd","text":"","code":"#' @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, ...})"},{"path":[]},{"path":"https://roxygen2.r-lib.org/dev/reference/tags-reuse.html","id":null,"dir":"Reference","previous_headings":"","what":"Tags that help you reuse documentation — tags-reuse","title":"Tags that help you reuse documentation — tags-reuse","text":"Learn full details vignette('reuse'). Key tags: @describeIn ${1:destination} ${2:description}: Document function method destination topic. @inherit ${1:source} ${2:components}: Inherit one documentation components another topic. components omitted, supported components inherited. Otherwise, specify individual components inherit picking one params, return, title, description, details, seealso, sections, references, examples, author, source, note, format. @inheritDotParams ${1:source} ${2:arg1 arg2 arg3}: Automatically generate documentation ... passing dots along another function. @inheritParams ${1:source}: Inherit argument documentation another function. inherits documentation arguments already documented locally. @inheritSection ${1:source} ${2:section name}: Inherit specific named section another topic. @order ${1:number}: Override default (lexigraphic) order multiple blocks combined single topic. @rdname ${1:topic-name}: Override file name generated .Rd file. Can used combine multiple blocks single documentation topic. less frequently used tags: @eval ${1:r-code}: Evaluate arbitrary code package namespace insert results back block. return character vector lines. @evalRd ${1:r-code}: Evaluate arbitrary code package namespace insert results back block. return character vector lines. @includeRmd man/rmd/${1:filename}.Rmd: Insert contents .Rmd current block. Superseded favour using code chunk child document. @template ${1:path--template}: Use roxygen2 template. Now superseded favour inline R code. @templateVar ${1:name} ${2:value}: Define variables use roxygen2 template.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/tags-reuse.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Tags that help you reuse documentation — tags-reuse","text":"","code":"#' @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}"},{"path":[]},{"path":"https://roxygen2.r-lib.org/dev/reference/tags_list.html","id":null,"dir":"Reference","previous_headings":"","what":"Access metadata about built-in tags — tags_list","title":"Access metadata about built-in tags — tags_list","text":"Access metadata built-tags","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/tags_list.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Access metadata about built-in tags — tags_list","text":"","code":"tags_list(built_in = TRUE) tags_metadata()"},{"path":"https://roxygen2.r-lib.org/dev/reference/update_collate.html","id":null,"dir":"Reference","previous_headings":"","what":"Update Collate field in DESCRIPTION — update_collate","title":"Update Collate field in DESCRIPTION — update_collate","text":"default, R loads files alphabetical order. Unfortunately every alphabet puts letters order, rely alphabetic ordering need one file loaded another. (usually matter important S4, need make sure classes loaded subclasses generics defined methods.). can override default alphabetical ordering @include .R, specify .R must loaded current file. Generally, need run function ; run automatically package needs load R files collation order.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/update_collate.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Update Collate field in DESCRIPTION — update_collate","text":"","code":"update_collate(base_path)"},{"path":"https://roxygen2.r-lib.org/dev/reference/update_collate.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Update Collate field in DESCRIPTION — update_collate","text":"base_path Path package directory.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/update_collate.html","id":"collate","dir":"Reference","previous_headings":"","what":"Collate","title":"Update Collate field in DESCRIPTION — update_collate","text":"roclet roclets need values objects package, values can generated unless sourced files, source files unless know correct order. @include tags, roxygen2 leave collate . makes easier use roxygen2 existing collate directive, remove @include tags, need also manually delete collate field.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/update_collate.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Update Collate field in DESCRIPTION — update_collate","text":"","code":"#' 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 #> NULL"},{"path":"https://roxygen2.r-lib.org/dev/reference/vignette_roclet.html","id":null,"dir":"Reference","previous_headings":"","what":"Re-build outdated vignettes — vignette_roclet","title":"Re-build outdated vignettes — vignette_roclet","text":"roclet rebuilds outdated vignettes tools::buildVignette, longer recommend longer recommend storing built vignettes package. default, rebuild vignettes source file newer output pdf html. (means automatically re-build vignette change vignette source, change R code). want finer control, add Makefile vignettes/ roxygen2 use instead. prevent RStudio re-building vignettes checking package, add ---build-vignettes \"Build Source Package\" field project options.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/vignette_roclet.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Re-build outdated vignettes — vignette_roclet","text":"","code":"vignette_roclet()"},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-development-version","dir":"Changelog","previous_headings":"","what":"roxygen2 (development version)","title":"roxygen2 (development version)","text":"S3 method export warning longer fails class contains { } (#1575). @family lists now ordered carefully, “foo1” comes “foo” (#1563, @krlmlr). Re-runs namespace_roclet() fixed packages using multi-line @rawNamespace directives (#1572, @MichaelChirico). @importFrom works quoted non-syntactic names, e.g. @importFrom magrittr \"%>%\" @importFrom rlang `:=`, broken 7.3.0 (#1570, @MichaelChirico). unquoted form @importFrom magrittr %>% continues work. Relatedly, @importFrom directives matching known functions (e.g. @importFrom utils plot pdf) produce valid NAMESPACE files .","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-730","dir":"Changelog","previous_headings":"","what":"roxygen2 7.3.0","title":"roxygen2 7.3.0","text":"CRAN release: 2024-01-11","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"new-features-7-3-0","dir":"Changelog","previous_headings":"","what":"New features","title":"roxygen2 7.3.0","text":"@docType package now works like documenting \"_PACKAGE\", creating {packagename}-package alias clearly suggesting switch \"_PACKAGE\" instead (#1491). _PACKAGE longer generate alias package name function name exists (#1160). NAMESPACE roclet now reports S3 methods missing @export tag. S3 methods need @exported (confusingly really registers method) even generic . avoids rare, hard debug, problems (#1175). can suppress warning @exportS3Method NULL (#1550). NAMESPACE roclet regenerates imports loading package code parsing roxygen blocks. goal long time (#372), accidentally broke adding support code execution markdown blocks. resolves family problems somehow bork NAMESPACE can’t easily get can’t re-document package code doesn’t reload.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"minor-improvements-and-bug-fixes-7-3-0","dir":"Changelog","previous_headings":"","what":"Minor improvements and bug fixes","title":"roxygen2 7.3.0","text":"document function another package automatically imported. Additionally, set @rdname @name can opt default reexports topic generation provide docs (#1408). Generate correct usage S4 methods non-syntactic class names. ROXYGEN_PKG env var provides name package documented (#1517). @describeIn foo now suggests might want @rdname instead (#1493). also gives informative warning use unsupported type (#1490). DESCRIPTION, URLs containing escapes URL BugReports now correctly handled (@HenningLorenzen-ext-bayer, #1415). Authors can now multiple email addresses (@jmbarbone, #1487). escape_examples() now exported (#1450). @exportS3Method provides needed metadata generate correct usage S3 methods, just like @method (#1202). is_s3_generic() now ignores non-function objects looking candidate function. believe closer R operates. @import friends now ignored try import package documented. useful add self-dependencies standalone files meant used packages (r-lib/usethis#1853). @importFrom throws friendlier error try import non-existing functions (@MichaelChirico, #1409). @include now gives informative warning use path doesn’t exist (#1497). @inherit can now also inherit @format (#1293).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-723","dir":"Changelog","previous_headings":"","what":"roxygen2 7.2.3","title":"roxygen2 7.2.3","text":"CRAN release: 2022-12-08 roxygen2 now supports HTML blocks markdown. included HTML manual. can also produced output code chunks. Improved support RStudio IDE.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-722","dir":"Changelog","previous_headings":"","what":"roxygen2 7.2.2","title":"roxygen2 7.2.2","text":"CRAN release: 2022-11-11 @includeRmd calls local_reproducible_output() make code run included .Rmds consistent sources (#1431). Fix duplicated argument roxy_block() avoid CRAN removal.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-721","dir":"Changelog","previous_headings":"","what":"roxygen2 7.2.1","title":"roxygen2 7.2.1","text":"CRAN release: 2022-07-18","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"tags-7-2-1","dir":"Changelog","previous_headings":"","what":"Tags","title":"roxygen2 7.2.1","text":"built-tags now documented can (e.g.) ?\"@param\" get basic description @param pointer learn (#1165). powered new tags_list() lists tags defined roxygen2 tags_metadata() provides useful information use (e.g.) IDEs (#1375). @describeIn can now used combine types functions (generics, methods functions) single topic. resulting section organises functions type (#1181) displays methods like function calls. Methods recognized extend generic destination,destination can heuristically identified constructor. Code evaluated inline markdown code chunks @eval/@evalRd/ @evalNamespace now evaluated environment designed reproducible suppress output won’t work Rd (e.g. turning colour unicode support cli) (#1351). now also set knitr options comment = #> (#1380) collapse = TRUE (#1376). @export now export class constructor function applied expressions like foo <- setClass(\"foo\") (#1216). @includeRmd now gives better feedback fails (#1089).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"rmarkdown-7-2-1","dir":"Changelog","previous_headings":"","what":"(R)markdown","title":"roxygen2 7.2.1","text":"New knitr_chunk_options option (Roxygen entry DESCRIPTION man/roxygen/meta.R) added knitr chunk options roxygen2 uses markdown code blocks inline code (#1390). PDF figures included PDF manual, SVG figures included HTML manual (#1399). can now use alternative knitr engines markdown code blocks (#1149). Generated HTML code blocks never includes “NA” language (#1251). Using level 1 heading wrong tag now gives useful warning (#1374). Fix bug interpolating results indented inline RMarkdown (#1353).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"other-7-2-1","dir":"Changelog","previous_headings":"","what":"Other","title":"roxygen2 7.2.1","text":"daily build RStudio, lists changed Rd files now clickable can immediately see rendered development documentation (#1354). R6 documentation longer shows inherited methods aren’t (#1371), links superclass docs ’re actually available (#1236). Automated usage longer mangles nbsp default arguments (#1342).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-720","dir":"Changelog","previous_headings":"","what":"roxygen2 7.2.0","title":"roxygen2 7.2.0","text":"CRAN release: 2022-05-13","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"new-features-7-2-0","dir":"Changelog","previous_headings":"","what":"New features","title":"roxygen2 7.2.0","text":"NAMESPACE roclet now preserves existing non-import directives ’s first pre-processing pass. eliminates “NAMESPACE changed” messages reduces incidence namespace borking (#1254). @inheritParams now inherits exact multiparameter matches, ’re inheriting function @param x,y ’ll get parameter documentation function needs docs x y (#950). warning messages reviewed informative actionable (#1317). @title now checks multiple paragraphs. @export gives informative warning contains many lines. (#1074). tags warn now provide whitespace (#1228), problems first tag block reported correct line number (#1235). daily build RStudio, roxygen2 warnings now include clickable hyperlink take directly problem (#1323). technology active development across IDE cli package extremely exciting.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"minor-improvements-and-bug-fixes-7-2-0","dir":"Changelog","previous_headings":"","what":"Minor improvements and bug fixes","title":"roxygen2 7.2.0","text":"roxygen2 can read UTF-8 paths windows (#1277). @authors de-duplicated merged documentation (@DanChaltiel, #1333). @exportS3method pkg::generic now works pkg::generic isn’t imported package (#1085). @includeRmd now adapted change rmarkdown 2.12 regarding math support github_document() (#1304). @inherit friends perform less aggressive link tweaking, eliminating many spurious warnings. Additionally, get warning, ’ll now always learn topic ’s coming (#1135). Inherited \\ifelse{}{}{} tags now inserted correctly (without additional {}) (#1062). @inherit now supports inheriting “Notes” @inherit pkg::fun note (@pat-s, #1218) Automatic @usage now correctly wraps arguments containing syntactically significant whitespace (e.g anonymous functions) (#1281) non-syntactic values surrounded backticks (#1257). Markdown: Code blocks always wrapped
even language unknown (#1234). Links markup (e.g. [foo `bar`][target]) now cause informative warning instead generating invalid Rd. Curly braces links now escaped (#1259). Inline R code now powered knitr. available, (knit) print methods applied (#1179). change alters outputs brings roxygen line console R markdown behavior. x <- \"foo\" longer inserts anything resulting documentation, x <- \"foo\"; x . also means returning character vector insert commas components, newlines. roxygen2 longer generates invalid HTML (#1290). DOIs, arXiv links, urls Description field DESCRIPTION now converted appropriate Rd markup (@dieghernan, #1265, #1164). DOIs URL field DESCRIPTION now converted Rd’s special \\doi{} tag (@ThierryO, #1296).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-712","dir":"Changelog","previous_headings":"","what":"roxygen2 7.1.2","title":"roxygen2 7.1.2","text":"CRAN release: 2021-09-08 new @examplesIf tag can used create conditional examples. examples run specified condition holds (#962). roxygen2 now licensed MIT (#1163). Bug fix upcoming stringr 2.0.0 release. Code blocks language now add sourceCode generated div; makes syntax highlighting consistent across downlit/pandoc/knitr/roxygen2. Percent signs markdown link targets, e.g. [text](https://foo/ba%20r) now handled correctly (#1209).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-711","dir":"Changelog","previous_headings":"","what":"roxygen2 7.1.1","title":"roxygen2 7.1.1","text":"CRAN release: 2020-06-27 processing cross package markdown links (e.g. [pkg::fun()]), roxygen2 now looks file needs link , instead linking topic, avoid “Non-file package-anchored links” R CMD check warnings. R6 methods re-exported functions always sorted C locale; ensures ’re always sorted way every environment (#1077). roxygen2 now supports inline markdown code code chunks inside Rd tags. particular \\{} (#1115).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-710","dir":"Changelog","previous_headings":"","what":"roxygen2 7.1.0","title":"roxygen2 7.1.0","text":"CRAN release: 2020-03-11","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"new-features-7-1-0","dir":"Changelog","previous_headings":"","what":"New features","title":"roxygen2 7.1.0","text":"roxygen2 now supports inline markdown code also code chunks, using notation knitr package. example: See vignette(\"rd-formatting\") details. roxygen2 now keeps using Windows (CR LF) line endings files already CR LF line endings, uses LF new files (#989).","code":"#' 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) #' ```"},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"minor-improvements-and-bug-fixes-7-1-0","dir":"Changelog","previous_headings":"","what":"Minor improvements and bug fixes","title":"roxygen2 7.1.0","text":"Auto-generated package documentation can now handle author ORCID comments containing full url (#1040). Hyperlinks R6 methods also added PDF manual (#1006). Empty annotations (alternate text) figures added via markdown now omitted. caused issues generating pkgdown web sites (#1051). Roxygen metadata can now packages element, giving character vector package names load. makes easier use extension package provide new tags existing roclets (#1013). See ?load_options details. @evalNamespace() works (#1022). @description NULL @details NULL longer fail; instead, tags ignored, except @description NULL package level documentation, can used suppress auto-generated Description section (#1008). Multiple @format tags now combined (#1015). warning @section titles spanning multiple lines now includes hint ’re missing colon (@maelle, #994). Can now document objects created delayedAssign() forcing evaluation documentation time (#1041)","code":"Roxygen: list(markdown = TRUE, packages = \"roxygenlabs\")"},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-702","dir":"Changelog","previous_headings":"","what":"roxygen2 7.0.2","title":"roxygen2 7.0.2","text":"CRAN release: 2019-12-02 \\example{} escaping improved (!) special escapes within strings correctly escaped (#990).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-701","dir":"Changelog","previous_headings":"","what":"roxygen2 7.0.1","title":"roxygen2 7.0.1","text":"CRAN release: 2019-11-22 @includeRmd now optional second argument, top level section included file go . defaults details section (#970). Code chunks now evaluated child global environment (#972). @inheritParams better job munging links. Links form \\link[=topic]{text} now automatically converted \\link[pkg:topic]{text} inherited packages (#979). Internal has_topic() helper better implementation; means links longer munged unnecessarily (#973). \\example{} escaping considerably simplified (#967), now documented escape_example(). \\usage{}, S3/S4 methods longer double-escaped (#976). Markdown tables cells contain multiple elements (e.g. text code) now rendered correctly (#985). Markdown code blocks containing operators special syntax (e.g. function, , +) now converted \\code{} \\verb{} (#971).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-700","dir":"Changelog","previous_headings":"","what":"roxygen2 7.0.0","title":"roxygen2 7.0.0","text":"CRAN release: 2019-11-12","code":""},{"path":[]},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"new-tags-7-0-0","dir":"Changelog","previous_headings":"New features","what":"New tags","title":"roxygen2 7.0.0","text":"@includeRmd {path.Rmd} converts .Rmd/.md file .Rd includes manual page. allows sharing text vignettes, README.Rmd, documentation. See vignette(\"rd\") details (#902). @order {n} tag controls order blocks processed. can use override usual ordering proceeds top file bottom. @order 1 processed @order 2, blocks don’t explicit order set (#863). @exportS3Method tag allows generate S3method() namespace directives (note different capitalisation) (#796). primary use “delayed” method registration, allows define methods generics found suggested packages (available R 3.6 greater). example, generate (See vctrs::s3_register() need version works earlier versions R). also two argument form allows generate arbitrary S3method() directives: New @returns alias @return (#952).","code":"#' @exportS3Method package::generic generic.foo <- function(x, ...) { } S3method(package::generic, foo) #' @exportS3Method generic class NULL S3method(generic, class)"},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"r6-7-0-0","dir":"Changelog","previous_headings":"New features","what":"R6","title":"roxygen2 7.0.0","text":"roxygen2 can now document R6 classes (#922). See vignette(\"rd\") details.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"markdown-improvements-7-0-0","dir":"Changelog","previous_headings":"New features","what":"Markdown improvements","title":"roxygen2 7.0.0","text":"Rd comments (%) now automatically escaped. need replace existing uses \\% % (#879). Markdown headings supported tags like @description, @details, @return (#907, #908). Level 1 headings create new top-level \\section{}. Level 2 headings create nested \\subsections{}. Markdown tables converted \\tabular{} macro (#290). roxygen2 supports GFM table syntax looks like : Markdown code (`foofy`) converted either \\code{} \\verb{}, depending whether parses R code. better matches description \\code{} \\verb{} macros, solves certain class escaping problems, make easier include arbitrary “code” snippets documentation without causing Rd failures (#654). Markdown links can now contain formatting, e.g. [*mean*][mean] now generate \\link[=mean]{\\emph{mean}}. Use unsupported markdown features (e.g. blockquotes, inline HTML, horizontal rules) generates informative error messages (#804).","code":"| foo | bar | | --- | --- | | baz | bim |"},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"default-usage-7-0-0","dir":"Changelog","previous_headings":"New features","what":"Default usage","title":"roxygen2 7.0.0","text":"default formatting function usage spans multiple lines now changed. Previously, usage wrapped produce smallest number lines, e.g.: Now wrapped argument gets line (#820): prefer old behaviour can put following DESCRIPTION:","code":"parse_package(path = \".\", env = env_package(path), registry = default_tags(), global_options = list()) parse_package( path = \".\", env = env_package(path), registry = default_tags(), global_options = list() ) Roxygen: list(old_usage = TRUE)"},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"code-loading-7-0-0","dir":"Changelog","previous_headings":"New features","what":"Code loading","title":"roxygen2 7.0.0","text":"roxygen2 now provides three strategies loading code (#822): load_pkgload(), default, uses pkgload. Compared previous release, now automatically recompiles package needed. load_source() attaches required packages source()s files R/. cruder simulation package loading pkgload (e.g. unreliable use S4 extensively), require package compiled. Use default strategy (used roxygen2 6.1.0 ) causes grief. load_installed() assumes installed package. best used part bigger automated workflow. can override default either calling (e.g.) roxygenise(load_code = \"source\")) setting load option DESCRIPTION: Roxygen: list(load = \"source\").","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"options-7-0-0","dir":"Changelog","previous_headings":"New features","what":"Options","title":"roxygen2 7.0.0","text":"well storing roxygen options Roxygen field DESCRIPTION can now also store man/roxygen/meta.R (#889). evaluation file produce named list maps option names values. roxygen now also looks templates man/roxygen/templates (#888). New rd_family_title option: named list, used overrides default “family:” prefix @family generates. example, override prefix generated @family foo place rd_family_title <- list(foo = \"Custom prefix: \") man/roxygen/meta.R (#830, @kevinushey).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"breaking-changes-7-0-0","dir":"Changelog","previous_headings":"","what":"Breaking changes","title":"roxygen2 7.0.0","text":"Rd comments (%) automatically escaped markdown formatted text. backward incompatible change need replace existing uses \\% % (#879). Using @docType package longer automatically adds -name. Instead document _PACKAGE get defaults package documentation, use @name override default file name. @S3method removed. deprecated roxygen2 4.0.0 released 2014-05-02, 5 years ago. Using old wrap option now trigger warning, hasn’t worked quite time. Suppress error deleting option DESCRIPTION.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"extending-roxygen2-7-0-0","dir":"Changelog","previous_headings":"Breaking changes","what":"Extending roxygen2","title":"roxygen2 7.0.0","text":"process extending roxygen2 new tags new roclets completely overhauled, now documented vignette(\"extending\"). ’re one people written roxygen2 extension, break code - documentation, object structure, print methods now much better hope ’s annoying! interface now documented, change future without warning deprecation cycle. previously made new roclet, major changes : previously internal data structures used represent blocks tags overhauled. now documented stable. See roxy_block() roxy_tag() details. roclet_tags() longer used; instead define roxy_tag_parse() method. example, create new @mytag tag, generate class roxy_tag_mytag, parsed roxy_tag_parse.roxy_tag_mytag() method. method return new roxy_tag() object val field set. means registry argument longer needed removed. rd_section() roxy_tag_rd() now exported can easily extend rd_roclet() tags generate output .Rd files. global_options longer passed roclet methods. Instead, use roxy_meta_get() retrieve values stored options (#918). tag_two_part() tag_words() now simple functions, function factories. tag_markdown_restricted() removed exactly thing tag_markdown(). big thanks goes @mikldk starting vignette motivating make extension process much pleasant (#882).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"bug-fixes-and-minor-improvements-7-0-0","dir":"Changelog","previous_headings":"","what":"Bug fixes and minor improvements","title":"roxygen2 7.0.0","text":"Empty roxygen2 lines start block now silently removed (#710). Whitespace automatically trimmed RoxygenNote field comparing installed version roxygen2 version used generate documentation (#802). Files generated Windows systems now retain existing line endings, use unix-style line endings new files (@jonthegeek, @jimhester, #840). roxygen2 now recognises fully qualified S4 functions like methods::setGeneric(), methods::setClass() methods::setMethod() (#880). Package documentation now converts ORCIDs useful link (#721). package logo (found man/images/logo.png) now scaled 120px wide (@peterdesmet, #834). Documenting S4 method .local() wrapper longer fails obscure error message (#847). Functions documented reexports now sorted alphabetically package (#765). @describeIn can now used combination function types (#666, #848). @description @detail tags automatically generated leading description block, now correct line numbers (#917). @example @examples interwoven order appear (#868). @examples, escaped ' \" strings longer doubly escaped (#873). @family automatically adds () linking functions (#815), print link line (improve diffs). @inheriting external documentation, \\link{foo} links automatically transformed \\link{package}{foo} work generated documentation (#635). \\href{} links external inherited now inserted correctly (without additional {}) (#778). @inheriting function arguments longer throws confusing error message (#898). @inheritDotParams automatically ignores arguments can’t inherited ... used current function (@mjskay, #885). @inheritDotParams includes link function wraps parameters \\code{} (@halldc, #842). @inheritDotParams can repeated inherit dot docs multiple functions (@gustavdelius, #767). @inheritDotParams avoids multiple ... arguments (@gustavdelius, #857). @inheritParams ignores leading dots comparing argument names (#862). @inheritParams warns parameters require documentation (#836). @param containing whitespace gives clear warning message (#869). Multiple @usage statements single block now generate warning. Previously, first used without warning.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-611","dir":"Changelog","previous_headings":"","what":"roxygen2 6.1.1","title":"roxygen2 6.1.1","text":"CRAN release: 2018-11-07 Now specifically imports recent version desc package (>= 1.2.0) fix various parsing issues (@crsh, #773, #777, #779). Multi-line DESCRIPTION collate directives now correctly parsed windows (@brodieG, #790). roxygenise() longer recompiles packages containing src code (#784). roxygenise() now stops informative error message run directory ’s package root (@mikmart, #704).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-610","dir":"Changelog","previous_headings":"","what":"roxygen2 6.1.0","title":"roxygen2 6.1.0","text":"CRAN release: 2018-07-27","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"new-features-6-1-0","dir":"Changelog","previous_headings":"","what":"New features","title":"roxygen2 6.1.0","text":"NAMESPACE roclet now works two passes - first generates NAMESPACE containing import directives can generated without evaluating code package. alleviates problem previously possible get state get carefully editing NAMESPACE hand (#372). @evalRd foo() evaluates foo() defined package namespace inserts results current block (#645). code return character vector one entry line (start #'). two small limitations current implementation: generated roxygen affect @md/@noMd status @evalRd work inside templates. @evalNamespace NAMESPACE @evalRd Rd files: give R code produces literal entry NAMESPACE run. make easier export functions generated functions package (#531, @egnha). @inherits can now inherit examples (#588). vignette(\"rd\") received thorough updating current best-practices. vignette still needs work pull requests greatly appreciated (#650). roxygenise() uses pkgload::load_all() instead home grown solution simulate package loading (needed roxygen2 uses run-time information generate documentation). reduce S4 related problems ensures devtools::document() roxygenise() always exactly behaviour (#568, #595). inherited section found, warning contains help page section requested (#732, @krlmlr). roxygen2 now always reads writes using UTF-8 encoding. used package Encoding: UTF-8 DESCRIPTION, ’ll now get warning (#564, #592).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"extension-api-6-1-0","dir":"Changelog","previous_headings":"","what":"Extension API","title":"roxygen2 6.1.0","text":"Roxygen blocks now official structure encoded roxy_block(). named list containing tags attributes providing metadata. parsed argument roclet_process() replaced separate blocks env arguments. New roclet_preprocess() generic makes possible roclets perform actions code evaluated. parse_package(), parse_file() parse_code() provide exported API allows use roxygen’s parsing code independently creating roclets.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"minor-improvements-and-bug-fixes-6-1-0","dir":"Changelog","previous_headings":"","what":"Minor improvements and bug fixes","title":"roxygen2 6.1.0","text":"tags (including @alias) now de-duplicated consistently sorted. reduces spurious diffs (#586, @flying-sheep). @concept now generates one \\concept per tag (#611). default @description (.e. title) now added much later process. means @inherit description now works specified title inheritor (#629) default description slightly nicer merging multiple blocks. @family automatically adds value concepts (#611). @inherits: mechanism extracting inherited Rd better job preserving escapes (#624) Empty .Rbuildignore now handled correctly (#576). Stricter regular expression ensures files ending .R .r parsed roxygen comments (#625). Objects names starting dot now default documented files prefix ‘dot-’. Roclets can now access global options designed. allows templates use markdown formatting set globally (#594). can now autogenerate package documentation even don’t Authors@R (#606). Multiple given /family names now supported Authors@R field DESCRIPTION file (#672, @sgibb). package logo exists (man/figures/logo.png) automatically included generated package docs (#609). Usage data objects now correctly generated, avoiding double escaping components usage (#562). Improvements markdown translation: Code link text now properly rendered code (#620, @egnha). Whitespace words link text now preserved single space links form [text][fcn] [text](URL) (#628, #754, #760, @egnha @jennybc). % inline code (#640), code blocks (@nteetor, #699) links (#724) now automatically escaped. Parsing markdown links tweaked reduce false positives (#555). still get false positive, can now put \\\\ front [ avoid converted link (#720). Links can longer followed { avoid spurious matches Rd commands like \\Sexpr{}. Unsupported markdown features now generate mildly helpful warning instead throwing utterly useless error (#560). person() now supports MARC Relator role codes (#662, @publicus). topic_add_usage() now outputs formatted “Usage” section max width 80 characters thanks now flexible wrap_string() (@JoshOBrien, #719).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-601","dir":"Changelog","previous_headings":"","what":"roxygen2 6.0.1","title":"roxygen2 6.0.1","text":"CRAN release: 2017-02-06 Allowing empty lines .Rbuildignore. Previously, empty lines caused files ignored. (#572, @jakob-r) Automatically generating usage section infix function containing “<-” longer removes “<-” function name (#554).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-600","dir":"Changelog","previous_headings":"","what":"roxygen2 6.0.0","title":"roxygen2 6.0.0","text":"CRAN release: 2017-01-31","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"markdown-6-0-0","dir":"Changelog","previous_headings":"","what":"Markdown","title":"roxygen2 6.0.0","text":"fields can now written using Markdown markup instead traditional Rd language. can turn Markdown globally adding Roxygen: list(markdown = TRUE) DESCRIPTION. @md / @noMd tags turn Markdown parsing / given block. See vignette(\"markdown\") details (#364, #431, #499, #506, #507), @gaborcsardi","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"improved-inheritance-6-0-0","dir":"Changelog","previous_headings":"","what":"Improved inheritance","title":"roxygen2 6.0.0","text":"New @inheritDotParams allows automatically generate parameter documentation ... common case pass ... another function (#512). often override arguments, comes flexible specification argument selection: @inheritDotParams foo takes parameters foo() @inheritDotParams foo b e:h takes parameters , b, parameters e h @inheritDotParams foo -x -y takes parameters except x y. documentation generated similar style used ?plot eventually incorporated RStudio’s autocomplete. New @inherit generalises @inheritParams, allows inherit parameters, return, references, title, description, details, sections, seealso. default @inherit my_fun inherit , can document object entirely specifying @inherit tag. Alternatively, can select specific tags inherit @inherit my_fun return params (#384). New @inheritSection fun title allows inherit contents single section another topic (#513). @inheritParams now works recursively, can inherit parameters function inherited parameters somewhere else. also better handles \\dots alias ... (#504).","code":""},{"path":[]},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"tags-6-0-0","dir":"Changelog","previous_headings":"Minor improvements and bug fixes","what":"Tags","title":"roxygen2 6.0.0","text":"@aliases longer sorted alphabetically, instead match order usage. gives control pkgdown. @describeIn now escapes special characters function names (#450). @family see alsos added order appear, alphabetically (#315). Fixed issue .s sometimes added words within @family tag (#477, @kevinushey). @author rendered @seealso. @example gives nice warning message accidentally use instead @examples (#494). Multiple @examples sections merged (#472, @krlmlr). Roxygen longer write topics don’t name title, instead generate warning. makes easier detect ’ve accidentally used @rdname incorrect value (#474).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"s3-6-0-0","dir":"Changelog","previous_headings":"Minor improvements and bug fixes","what":"S3","title":"roxygen2 6.0.0","text":"Non-primitive, internal S3 generics (e.g. ‘rbind’, ‘cbind’) now properly detected S3 generics. (#488, @kevinushey) Ensure functions S3 class still treated functions (#455). S3 method declarations via R.methodS3::setMethodS3() function declarations via R.oo::setConstructorS3() now supported (@HenrikBengtsson, #525).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"s4-6-0-0","dir":"Changelog","previous_headings":"Minor improvements and bug fixes","what":"S4","title":"roxygen2 6.0.0","text":"can now document setClassUnion()s (#514). default alias S4 method now re-adds trailing signatures sometimes dropped (#460). Back references now wrapped multiple lines, long (#493, @LiNk-NY).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"other-6-0-0","dir":"Changelog","previous_headings":"Minor improvements and bug fixes","what":"Other","title":"roxygen2 6.0.0","text":"\"_PACKAGE\" documentation now generates default @seealso combining URL BugReport fields, default @author field generated Authors@R field (#527). now works roxygenise(); worked devtools::document() (#439, @krlmlr). Manually created NAMESPACE documentation files never overwritten, even using roxygen2 first time (@krlmlr, #436). Changes DESCRIPTION (.e. Collate: RoxygenNote) now use desc package. minimise spurious changes (#430). default_data_format() renamed object_format(). New roclet_find() provides flexible way specify roclets: roclet name (e.g. “rd_roclet”), package (“foo::roclet_bar”), options (“foo::roclet_bar(baz = TRUE)”). usage replacement functions uses non-breaking spaces <- never get put line (#484). Roxygen now parses nonASCII documentation correctly (long UTF-8 encoded specified Encoding DESCRIPTION) (#532, @shrektan), ignores files listed .Rbuildignore (#446, @fmichonneau).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"extending-roxygen2-6-0-0","dir":"Changelog","previous_headings":"","what":"Extending roxygen2","title":"roxygen2 6.0.0","text":"Deprecated register.preref.parser() register.preref.parsers() removed. register_tags() also removed favour new roclet_tags() generic. roclet() (constructor), roclet_tags(), roclet_process() roclet_output(), roc_clean() now exported making possible create roclets packages. Helper functions roxy_tag() roxy_tag_warning() also exported. new_roclet() longer exported - use roclet() instead.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-501","dir":"Changelog","previous_headings":"","what":"roxygen2 5.0.1","title":"roxygen2 5.0.1","text":"CRAN release: 2015-11-11 Use ls(), names() list elements environment: fixes R 3.1.0 incompatibility (#422, @kevinushey). @export allows trailing new line (#415). Fixed bug @noRd, usage cause error (#418).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-500","dir":"Changelog","previous_headings":"","what":"roxygen2 5.0.0","title":"roxygen2 5.0.0","text":"CRAN release: 2015-10-28","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"new-features-5-0-0","dir":"Changelog","previous_headings":"","what":"New features","title":"roxygen2 5.0.0","text":"Roxygen now records version single place: RoxygenNote field DESCRIPTION (#338). last time roxygen2 upgrade changes every file man/. can now easily re-export functions ’ve imported another package: imported--re-exported functions documented file (rexports.Rd), containing brief description links original documentation (#376). can easily generate package documentation documenting special string “_PACKAGE” (@krlmlr, #349): title description automatically filled DESCRIPTION. New tags @rawRd @rawNamespace allow insert raw (unescaped) Rd NAMESPACE (useful conditional imports). @evalRd() similar, instead literal Rd, give R code produces literal Rd code run. make easier experiment new types output (#385). roxygen2 now parses source code files order specified Collate field DESCRIPTION. improves ordering generated documentation using @describeIn /@rdname split across several .R files, often happens working S4 (#323, #324).","code":"#' @export magrittr::`%>%` #' @details Details \"_PACKAGE\""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"minor-features-and-bug-fixes-5-0-0","dir":"Changelog","previous_headings":"","what":"Minor features and bug fixes","title":"roxygen2 5.0.0","text":"contents documented functions now also parsed roxygen comments. allows, e.g., documenting parameter’s type close type checked, documenting implementation details close source, simplifies future extensions documentation R6 classes (#397, @krlmlr). Data objects get simpler default @format describes object’s class dimensions. former default, generated generated str(), didn’t usually produce useful output quite slow. new S3 generic default_data_format() generates format can overridden generate custom format (#410, @krlmlr). roxygen parsers completely rewritten C++ (#295). gives nice performance boost gives: Better error messages: now get exact line number tag, just start block. parser simplified little: tags now must always start new line. recommended practice anyway, means escaping inline @ (@@) now optional. (#235) Unknown tags now emit warning, rather error. @examples longer complains non-matching braces inside strings (#329). @family now cross-links manual page , instead linking aliases (@gaborcsardi, #283, #367). special @include parser also rewritten C++, giving performance boost larger packages (#401). particularly important ’s also called devtools::load_all(). Additionally, space @include longer necessary (@krlmlr, #342). @inheritParams foo::bar ensures % remains escaped (#313). document multiple arguments one @param, (e.g. @param ,b,c) parameter get space can wrapped generated Rd file (#373). @sections identical titles now merged together, just like @description @details. useful conjunction @rdname tag. (@krlmlr, #300). Automatic @usage now correctly generated functions string arguments containing \"\\\"\" (#265). load_options() now exported devtools::document() doesn’t run update_collate() twice (#395). update_collate() rewrites Collate entry DESCRIPTION file changes (#325, #723). empty NAMESPACE file written maintained roxygen2 (@krlmlr, #348). Data lazy-loaded can documented (@krlmlr, #390).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"internal-changes-5-0-0","dir":"Changelog","previous_headings":"","what":"Internal changes","title":"roxygen2 5.0.0","text":"register.preref.parser() register.preref.parsers() deprecated - please use register_tags() instead. Parser callbacks registered register_tags() now called fields parsed “introduction” (text first tag) (@gaborcsardi, #370).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-411","dir":"Changelog","previous_headings":"","what":"roxygen2 4.1.1","title":"roxygen2 4.1.1","text":"CRAN release: 2015-04-15 Formatting Authors@R field DESCRIPTION file now retained (@jranke, #330). collate roclet falls back base::strwrap() generating collate field. makes roxygen2 compatible next version stringr. New “vignette” roclet. vignette automatically rebuilds date vignettes (#314). --one error C++ Roxygen preparser fixed. new @backref tag makes possible override sourceref R code generators like Rcpp (@krlmlr, #291, #294).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-410","dir":"Changelog","previous_headings":"","what":"roxygen2 4.1.0","title":"roxygen2 4.1.0","text":"CRAN release: 2014-12-13 source documentation added autogenerated .Rd files. @include tags, roxygen2 leaves collate field alone. makes easier convert existing project uses predefined collate, start @include later remove , ’ll need also remove collate field (#302, #303). Protected dir() sort_c() - ’d noticed inconsistency ordering devtools::document() devtools::check() cause . Fixed broken regular expression caused problems stringr 1.0.0. Authors@R field DESCRIPTION now longer wrapped(@krlmlr, #284). @describeIn plain functions now correctly includes function name can applied data documentation. (@jimhester, #285, #288). Works called Rscript methods loaded (@krlmlr, #305).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-402","dir":"Changelog","previous_headings":"","what":"roxygen2 4.0.2","title":"roxygen2 4.0.2","text":"CRAN release: 2014-09-02 don’t use @exports namespace directives, namespace file touched (#276). Methods longer automatically attempt inherit parameters generic. ’s fraught difficulty (#261). Roxygen now understands setReplaceMethod() (#266). Parameter documentation ordered according order formals, possible (@krlmlr, #63). Export is_s3_method(). Roxygen longer fails run non-UTF-8 locales windows.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-401","dir":"Changelog","previous_headings":"","what":"roxygen2 4.0.1","title":"roxygen2 4.0.1","text":"CRAN release: 2014-05-17 Explicit updateRoxygen() longer needed - roxygenize() right thing first time run. Exporting S4 generic works (#246). roxygenise() longer complains absence wrap field ’s unlikely anyone wants old behaviour (#245).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-400","dir":"Changelog","previous_headings":"","what":"roxygen2 4.0.0","title":"roxygen2 4.0.0","text":"CRAN release: 2014-05-02 roxygen2 4.0.0 major update roxygen2 makes provides enhanced error handling considerably safer default behaviour. Now, roxygen2 never overwrite file create. means run first time, ’ll need run roxygen2::upgradeRoxygen(). flag existing files created roxygen2.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"new-features-4-0-0","dir":"Changelog","previous_headings":"","what":"New features","title":"roxygen2 4.0.0","text":"Six vignettes provide comprehensive overview using roxygen2 practice. Run browseVignettes(\"roxygen2\") access. @describeIn makes easier describe multiple functions one file. especially useful want document methods generic, common class, ’s also useful want document multiple related functions one file (#185). @field documents fields reference class (#181). works way @slot S4 classes. can now document objects defined elsewhere (like datasets) documenting name string (#221). example, document dataset called mydata, can : roxygen2 now adds comment generated files know ’ve generated, hand edited. roxygen2 longer wraps text Rd files default, .e. default option wrap = FALSE now. override , specify field Roxygen: list(wrap = TRUE) DESCRIPTION (#178). Roxygenise automatically deletes --date Rd files man/.","code":"#' Mydata set #' #' Some data I collected about myself \"mydata\""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"improved-error-handling-4-0-0","dir":"Changelog","previous_headings":"","what":"Improved error handling","title":"roxygen2 4.0.0","text":"roxygen2 never overwrite file generated roxygen2. means first time use version roxygen, ’ll need delete existing Rd files. roxygenise() gains clean argument automatically remove files previously created roxygen2. Parsing stricter: many issues previously warnings now errors. errors now give line number roxygen block associated error. Every input now checked make sure matching braces (e.g. every { matching }). prevent frustrating errors require careful reading .Rd files (#183). @section titles @export tags can now span single line prevent common bugs. @S3method deprecated - just use @export (#198). Namespace tags now throw parsing errors give bad inputs (#220). Better error message try document something NULL, assignment, class, generic method (#194).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"bug-fixes-and-minor-improvements-4-0-0","dir":"Changelog","previous_headings":"","what":"Bug fixes and minor improvements","title":"roxygen2 4.0.0","text":"Better parsing non-syntactic function names packages used @inheritParams (#236). Deprecated arguments roxygenise() (roxygen.dir, copy.package, overwrite, unlink.target) removed. Remove unneeded codetools tools dependencies. Bump required Rcpp version 0.11.0, remove custom makefiles. Non-syntactic argument names (like _x) now surrounded back-ticks usage (#191). internal parsers longer part public roxygen2 interface. Usage statements generated roxygen statements non-longer contain non-ASCII characters wrapped long (#180). default, reference classes now document methods, methods parents (#201). Default aliases always include original name object, even overridden @name. also means <- setClass(\"\") get two aliases default: -class (#202). Use @aliases NULL suppress default alias. Non-syntactic class names (like <-) now escaped usage section S4 methods (#205). Eliminated two cases wrapping occurred even wrap = FALSE.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-310","dir":"Changelog","previous_headings":"","what":"roxygen2 3.1.0","title":"roxygen2 3.1.0","text":"CRAN release: 2014-01-29","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"documentation-for-reference-classes-3-1-0","dir":"Changelog","previous_headings":"","what":"Documentation for reference classes","title":"roxygen2 3.1.0","text":"’s now possible document reference classes, using “docstring” convention described ?setRefClass. want provide short paragraph description method , make first component message string containing description, e.g.: Unlike documentation R functions, documentation methods can quite succinct. Roxygen adopts convention documented methods public, listed man page object. Undocumented methods private shown documentation. methods superclasses also listed, don’t need flip multiple pages documentation understand can object. documented methods placed bulleted list section titled “Methods”, method usage automatically prepended docstring.","code":"setRefClass(\"A\", methods = list( f = function(a, b) { \"Take numbers \\code{a} and \\code{b} and add them together\" a + b } ))"},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"minor-fixes-and-improvements-3-1-0","dir":"Changelog","previous_headings":"","what":"Minor fixes and improvements","title":"roxygen2 3.1.0","text":"Fixes Rcpp 0.11.0 compatibility. roxygenise() now invisible returns list files generated individual roclets. useful tools want figure extra files man/ directory. is_s3_generic() now recognises group generics (#166). Don’t try add parameters data objects (#165). Sort output families using C locale (#171). @family now escapes function names references (#172).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-300","dir":"Changelog","previous_headings":"","what":"roxygen2 3.0.0","title":"roxygen2 3.0.0","text":"CRAN release: 2013-12-06 roxygen2 now fully supports S4 RC (reference classes) - longer need manually add @alias @usage tags S4 classes, methods generics, RC classes. default usage definitions much better, generating correct usage data sets (#122), S3 methods (without additional @method tag), S4 generics, S4 methods, replacement (#119) infix functions. Backslashes function arguments correctly escaped. Usage statements also use sophisticated line wrapping algorithm cause fewer problems R CMD check line limit. (#89, #125). S4 classes, S4 methods, RC classes given better default topics, file names corresponding topics shorter. S4 methods automatically inherit parameter documentation generic. @slot name description allows document slots S4 class. S3 support also improved: roxygen2 now figures whether function S3 method generic. (rare cases incorrectly, use @method manually describe generic class associated method). means can remove existing uses @method, can replace @S3method @export. Roxygen now support package specific options Roxygen field DESCRIPTION. value field R code results list. Currently wrap roclet values supported: Turn Rd re-wrapping adding Roxygen: list(wrap = FALSE) Change default roclets specifying Roxygen: list(roclets = c(\"collate\", \"rd\")) Roxygen 3.0 also includes number minor fixes improvements: Infix functions now escaped correctly NAMESPACE. (Thanks @crowding, #111) roxygenise() now works like devtools::document() ever works current directory. arguments roxygen.dir, overwrite, copy.package unlink.target deprecated due potential data loss problems. collate roclet longer roclet: processes R files using custom code (statically, dynamically) designed executed code sourced. Run update_collate() update Collate directive based @include tags - none present, collate directive generated. @useDynLib now works possible specifications - include comma tag value, output passed . means @useDynLib mypackage, .registration = TRUE now generate useDynLib(mypackage, .registration = TRUE) NAMESPACE. (#124) inst directory created default (#56). Explicitly depend utils methods packages make roxygen compatible Rscript (#72). Import digest package instead depending . Always use C locale sorting NAMESPACE file tags .Rd files. ensures consistent ordering across systems (#127). Templates extension .r supported case-sensitive file systems (#115). Template variables now actually work (#160, thanks @bronaugh). Suppress default aliases, format usage @aliases NULL, @format NULL @usage NULL.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-222","dir":"Changelog","previous_headings":"","what":"roxygen2 2.2.2","title":"roxygen2 2.2.2","text":"CRAN release: 2011-12-01 Correctly use keyword datasets dataset (Fixes #60) Reference classes longer given incorrect docType (data).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-221","dir":"Changelog","previous_headings":"","what":"roxygen2 2.2.1","title":"roxygen2 2.2.1","text":"CRAN release: 2011-11-19 Use unicode escapes test files tests pass platforms. Work around bug gsub C locale manually specifying Encoding().","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-22","dir":"Changelog","previous_headings":"","what":"roxygen2 2.2","title":"roxygen2 2.2","text":"CRAN release: 2011-11-12","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"new-features-2-2","dir":"Changelog","previous_headings":"","what":"New features","title":"roxygen2 2.2","text":"Package docType automatically add package alias, needed. (Fixes #4) Data docType automatically add datasets keyword, default usage, default format. (Fixes #5). Data docType automatically added data objects. New @encoding tag manually setting non-ASCII encodings needed. (Fixes #7)","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"bug-fixes-2-2","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"roxygen2 2.2","text":"write.description() now tries much harder respect users’ original DESCRIPTION field formatting instead forcibly re-wrapping certain fields 60 characters. @details @description now work correctly @useDynLib now works correctly: produces NAMESPACE file, instead separate (wrong) useDynLib statements . namespace import directives now behave way export directives, producing multiple single directives instead one multiple directive: @importClassesFrom pkg b now produces importClassesFrom(pkg, ) importClassesFrom(pkg, b) example files included @example can now use infix operators (e.g. %*%) things %, preceded backslash Rd file. behaviour already place examples directly included @examples. Aliases longer quoted, % escaped backslash (Fixes #24). Names also % escaped (Fixes #50) Replacement functions (e.g. foo<-) now get correct usage statements: foo() <- value instead foo()<-value. (Fixes #38) Functions arguments now correctly get usage statements (Fixes #35) Indentation examples now preserved (Fixes #27) roxygen2 replace characters valid filenames character substitute, e.g. [] becomes sub, <- becomes set (Fixes #6) Usage strings use non-breaking spaces prevent string default values containing whitespace split across multiple lines. may cause problems unlikely event default value containing non-breaking space (`“”’) (Fixes #21) Functions quoted names now get correct usage statements (Fixes #41) Objects longer exist documented (Fixes #42) Errors now display file name line number roxygen block help find problem. Thanks code contributions Renaud Gaujoux. (Fixes #13) Documentation untagged text @title, @description @details tags now produces correct output.","code":"@useDynLib packageName routine1 routine2 useDynLib(packageName, routine1) useDynLib(packageName, routine2)"},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-21","dir":"Changelog","previous_headings":"","what":"roxygen2 2.1","title":"roxygen2 2.1","text":"CRAN release: 2011-07-29","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"new-features-2-1","dir":"Changelog","previous_headings":"","what":"New features","title":"roxygen2 2.1","text":"package dependencies loaded automatically added support @source tag","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"bug-fixes-2-1","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"roxygen2 2.1","text":"NAMESPACE file longer needs exist Collate field DESCRIPTION longer needs exist = now recognised way assigning functions x$y <- function() {...} longer causes error @example longer added extra new-lines. Correct directory normalisation windows fixes broken test. special thanks goes Yihui Xie contributed fixes improvements (bar one) version!","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-20","dir":"Changelog","previous_headings":"","what":"roxygen2 2.0","title":"roxygen2 2.0","text":"CRAN release: 2011-07-23","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"major-changes-2-0","dir":"Changelog","previous_headings":"","what":"Major changes","title":"roxygen2 2.0","text":"now works run-time details give accurate output. requires source code roxygen documenting loaded prior documentation. roxygen attempt , need ensure required packages loaded. Run-time data fixes long standing bugs roxygen couldn’t correctly figure function usage. aware cases still need use @usage tag. written idiomatic R, uses S3 instead homegrown class system. roclets build internal data structure instead writing disk directly. means can now use @rdname tag merge documentation multiple functions one file, unique namespace directives written NAMESPACE (makes @importFrom much useful). features removed, may may (based feedback) reincluded. include callgraph roclet, R CMD roxygen, worked systems. templating system: use @template tag insert brew template stored man-roxygen. Template variables can set using @templateVar name value retrieved within template <%= name %> extensive use caching make repeated runs fast possible. clear caches guarantee complete rebuild, use clear_caches(). parsing “introduction” (text first tag) changed. Now title consists first paragraph (.e. text first empty line), second paragraph description others put details. component can overridden @title, @description @details appropriate.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"minor-changes-2-0","dir":"Changelog","previous_headings":"","what":"Minor changes","title":"roxygen2 2.0","text":"@name always output alias, even @aliases used. @export correctly uses @method generate S3method namespace directive","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"new-tags-2-0","dir":"Changelog","previous_headings":"","what":"New tags","title":"roxygen2 2.0","text":"@rdname filename sets output filename (without extension). Use functions non-alphanumeric functions (e.g. [<-) want document multiple functions one file @template templatename includes documentation template (see ) @section Section title: contents includes section title. Don’t forget colon! separates title section contents. @description @details tags allow specify description details components template @family family name automatically adds see-also cross-references functions family. function can belong multiple families. @inheritParams name allows inherit documentation parameters another function, either within current package (function) installed package (package:function). Currently supports single inheritance (.e. can’t inherit function inherits another function), can multiple @inheritParams tags. @format implemented; existed roxygen package actually ignored","code":""}] +[{"path":[]},{"path":"https://roxygen2.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"our-pledge","dir":"","previous_headings":"","what":"Our Pledge","title":"Contributor Covenant Code of Conduct","text":"members, contributors, leaders pledge make participation community harassment-free experience everyone, regardless age, body size, visible invisible disability, ethnicity, sex characteristics, gender identity expression, level experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, sexual identity orientation. pledge act interact ways contribute open, welcoming, diverse, inclusive, healthy community.","code":""},{"path":"https://roxygen2.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"our-standards","dir":"","previous_headings":"","what":"Our Standards","title":"Contributor Covenant Code of Conduct","text":"Examples behavior contributes positive environment community include: Demonstrating empathy kindness toward people respectful differing opinions, viewpoints, experiences Giving gracefully accepting constructive feedback Accepting responsibility apologizing affected mistakes, learning experience Focusing best just us individuals, overall community Examples unacceptable behavior include: use sexualized language imagery, sexual attention advances kind Trolling, insulting derogatory comments, personal political attacks Public private harassment Publishing others’ private information, physical email address, without explicit permission conduct reasonably considered inappropriate professional setting","code":""},{"path":"https://roxygen2.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"enforcement-responsibilities","dir":"","previous_headings":"","what":"Enforcement Responsibilities","title":"Contributor Covenant Code of Conduct","text":"Community leaders responsible clarifying enforcing standards acceptable behavior take appropriate fair corrective action response behavior deem inappropriate, threatening, offensive, harmful. Community leaders right responsibility remove, edit, reject comments, commits, code, wiki edits, issues, contributions aligned Code Conduct, communicate reasons moderation decisions appropriate.","code":""},{"path":"https://roxygen2.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"scope","dir":"","previous_headings":"","what":"Scope","title":"Contributor Covenant Code of Conduct","text":"Code Conduct applies within community spaces, also applies individual officially representing community public spaces. Examples representing community include using official e-mail address, posting via official social media account, acting appointed representative online offline event.","code":""},{"path":"https://roxygen2.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"enforcement","dir":"","previous_headings":"","what":"Enforcement","title":"Contributor Covenant Code of Conduct","text":"Instances abusive, harassing, otherwise unacceptable behavior may reported community leaders responsible enforcement codeofconduct@posit.co. complaints reviewed investigated promptly fairly. community leaders obligated respect privacy security reporter incident.","code":""},{"path":"https://roxygen2.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"enforcement-guidelines","dir":"","previous_headings":"","what":"Enforcement Guidelines","title":"Contributor Covenant Code of Conduct","text":"Community leaders follow Community Impact Guidelines determining consequences action deem violation Code Conduct:","code":""},{"path":"https://roxygen2.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"id_1-correction","dir":"","previous_headings":"Enforcement Guidelines","what":"1. Correction","title":"Contributor Covenant Code of Conduct","text":"Community Impact: Use inappropriate language behavior deemed unprofessional unwelcome community. Consequence: private, written warning community leaders, providing clarity around nature violation explanation behavior inappropriate. public apology may requested.","code":""},{"path":"https://roxygen2.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"id_2-warning","dir":"","previous_headings":"Enforcement Guidelines","what":"2. Warning","title":"Contributor Covenant Code of Conduct","text":"Community Impact: violation single incident series actions. Consequence: warning consequences continued behavior. interaction people involved, including unsolicited interaction enforcing Code Conduct, specified period time. includes avoiding interactions community spaces well external channels like social media. Violating terms may lead temporary permanent ban.","code":""},{"path":"https://roxygen2.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"id_3-temporary-ban","dir":"","previous_headings":"Enforcement Guidelines","what":"3. Temporary Ban","title":"Contributor Covenant Code of Conduct","text":"Community Impact: serious violation community standards, including sustained inappropriate behavior. Consequence: temporary ban sort interaction public communication community specified period time. public private interaction people involved, including unsolicited interaction enforcing Code Conduct, allowed period. Violating terms may lead permanent ban.","code":""},{"path":"https://roxygen2.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"id_4-permanent-ban","dir":"","previous_headings":"Enforcement Guidelines","what":"4. Permanent Ban","title":"Contributor Covenant Code of Conduct","text":"Community Impact: Demonstrating pattern violation community standards, including sustained inappropriate behavior, harassment individual, aggression toward disparagement classes individuals. Consequence: permanent ban sort public interaction within community.","code":""},{"path":"https://roxygen2.r-lib.org/dev/CODE_OF_CONDUCT.html","id":"attribution","dir":"","previous_headings":"","what":"Attribution","title":"Contributor Covenant Code of Conduct","text":"Code Conduct adapted Contributor Covenant, version 2.1, available https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. Community Impact Guidelines inspired [Mozilla’s code conduct enforcement ladder][https://github.com/mozilla/inclusion]. answers common questions code conduct, see FAQ https://www.contributor-covenant.org/faq. Translations available https://www.contributor-covenant.org/translations.","code":""},{"path":"https://roxygen2.r-lib.org/dev/LICENSE.html","id":null,"dir":"","previous_headings":"","what":"MIT License","title":"MIT License","text":"Copyright (c) 2023 roxygen2 authors Permission hereby granted, free charge, person obtaining copy software associated documentation files (“Software”), deal Software without restriction, including without limitation rights use, copy, modify, merge, publish, distribute, sublicense, /sell copies Software, permit persons Software furnished , subject following conditions: copyright notice permission notice shall included copies substantial portions Software. SOFTWARE PROVIDED “”, WITHOUT WARRANTY KIND, EXPRESS IMPLIED, INCLUDING LIMITED WARRANTIES MERCHANTABILITY, FITNESS PARTICULAR PURPOSE NONINFRINGEMENT. EVENT SHALL AUTHORS COPYRIGHT HOLDERS LIABLE CLAIM, DAMAGES LIABILITY, WHETHER ACTION CONTRACT, TORT OTHERWISE, ARISING , CONNECTION SOFTWARE USE DEALINGS SOFTWARE.","code":""},{"path":"https://roxygen2.r-lib.org/dev/SUPPORT.html","id":null,"dir":"","previous_headings":"","what":"Getting help with roxygen2","title":"Getting help with roxygen2","text":"Thanks using roxygen2. filing issue, places explore pieces put together make process smooth possible.","code":""},{"path":"https://roxygen2.r-lib.org/dev/SUPPORT.html","id":"making-a-reprex","dir":"","previous_headings":"","what":"Making a reprex","title":"Getting help with roxygen2","text":"Start making minimal reproducible example using reprex package. haven’t heard used reprex , ’re treat! Seriously, reprex make R-question-asking endeavors easier (pretty insane ROI five ten minutes ’ll take learn ’s ). additional reprex pointers, check Get help! section tidyverse site. roxygen2 issues can tricky create minimal reprex . two general techniques can help: know source problem, can often recreate using roc_proc_text() text snippet: ’s really helpful can spend little time reducing text absolute minimum. Make sure delete body function (since roxygen2 never looks ), try roxygen2 tag turn. leave tag ’ve confirmed ’s definitely part problem. Issues involve multiple files don’t give useful error messages harder track . cases, sometimes best option create copy package, progressively delete files problem goes away. ’ve done , sometimes ’ll able reduce problem call roc_proc_text() . , ’ll need make minimal package available somewhere internet (preferably github) link issue. can make package small possible, less time ’ll take find bug, time ’ll work .","code":"library(roxygen2) roc_proc_text(rd_roclet(), \" #' Title #' @param #' #' @export foo <- function() {}\" ) #> Error in FUN(X[[i]], ...): subscript out of bounds"},{"path":"https://roxygen2.r-lib.org/dev/SUPPORT.html","id":"where-to-ask","dir":"","previous_headings":"","what":"Where to ask","title":"Getting help with roxygen2","text":"Armed reprex, next step figure ask. ’s question: start community.rstudio.com, /StackOverflow. people answer questions. ’s bug: ’re right place, file issue. ’re sure: let community help figure ! problem bug feature request, can easily return report . opening new issue, sure search issues pull requests make sure bug hasn’t reported /already fixed development version. default, search pre-populated :issue :open. can edit qualifiers (e.g. :pr, :closed) needed. example, ’d simply remove :open search issues repo, open closed.","code":""},{"path":"https://roxygen2.r-lib.org/dev/SUPPORT.html","id":"general-advice","dir":"","previous_headings":"","what":"General advice","title":"Getting help with roxygen2","text":"efficient possible, development tidyverse packages tends bursty. Nothing happens long time, sufficient quantity issues accumulates, ’s burst intense activity focus efforts. makes development efficient avoids expensive context switching problems. process makes good reprex particularly important might multiple months initial report start working . can’t reproduce bug, can’t fix !","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/extending.html","id":"basics","dir":"Articles","previous_headings":"","what":"Basics","title":"Extending roxygen2","text":"Roxygen extensible user-defined roclets. means can take advantage Roxygen’s parser extend @tags. two primary ways extend roxygen2: Add new tag generates new top-level section .Rd files. Add new roclet anything like. vignette introduce key data structures roxygen2, show use two extension points. vignette rough, expected also read roxygen2 source code understand extension points. Hopefully, ’s useful enough help get started, problems, please file issue!","code":"library(roxygen2)"},{"path":"https://roxygen2.r-lib.org/dev/articles/extending.html","id":"key-data-structures","dir":"Articles","previous_headings":"","what":"Key data structures","title":"Extending roxygen2","text":"talk extending roxygen2, need first discuss two important data structures power roxygen: tags blocks.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/extending.html","id":"tags","dir":"Articles","previous_headings":"Key data structures","what":"Tags","title":"Extending roxygen2","text":"tag (list S3 class roxy_tag) represents single tag. following fields: tag: name tag. raw: raw contents tag (.e. everything end tag beginning next). val: parsed value, ’ll come back shortly. file line: location tag package. Used roxy_tag_warning() produce informative error messages. can construct tag objects hand roxy_tag(): However, rarely need , ’ll typically given block object, ’ll see shortly.","code":"roxy_tag(\"name\", \"Hadley\") #> [????:???] @name 'Hadley' {unparsed} str(roxy_tag(\"name\", \"Hadley\")) #> List of 5 #> $ file: chr NA #> $ line: chr NA #> $ raw : chr \"Hadley\" #> $ tag : chr \"name\" #> $ val : NULL #> - attr(*, \"class\")= chr [1:2] \"roxy_tag_name\" \"roxy_tag\""},{"path":"https://roxygen2.r-lib.org/dev/articles/extending.html","id":"blocks","dir":"Articles","previous_headings":"Key data structures","what":"Blocks","title":"Extending roxygen2","text":"block (list S3 class roxy_block) represents single roxygen block. following fields: tags: list roxy_tags. call: R code associated block (usually function call). file line: location R code. object: evaluated R object associated code. easiest way see basic structure roxy_block() generate one parsing roxygen block parse_text():","code":"text <- \" #' This is a title #' #' This is the description. #' #' @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 #> [:8] #> $tag #> [line: 2] @title 'This is a title' {parsed} #> [line: 4] @description 'This is the description.' {parsed} #> [line: 6] @param 'x,y A number' {parsed} #> [line: 7] @export '' {parsed} #> [line: 8] @usage '' {parsed} #> [line: 8] @.formals '' {parsed} #> [line: 8] @backref '' {parsed} #> $call f <- function(x, y) x + y #> $object #> $topic f #> $alias f"},{"path":"https://roxygen2.r-lib.org/dev/articles/extending.html","id":"adding-a-new--rd-tag","dir":"Articles","previous_headings":"","what":"Adding a new .Rd tag","title":"Extending roxygen2","text":"easiest way extend roxygen2 create new tag adds output .Rd files. requires two steps: Define roxy_tag_parse() method describes parse new tag. Define roxy_tag_rd() method describes convert tag .Rd commands. illustrate basic idea, ’ll create new @tip tag create bulleted list tips use function. idea take something like : generate Rd like : first step define method roxy_tag_parse() describes parse tag text. name class roxy_tag_{tag}, case roxy_tag_tip. function takes roxy_tag input, ’s job set x$val convenient parsed value used later roclet. want process text using Markdown can just use tag_markdown(): check works using parse_text(): (explicitly turn Markdown parsing using @md; ’s usually turned package using roxygen options). Next, define method roxy_tag_rd(), must create rd_section(). ’re going create new section called tip. contain character vector tips: additional layer needed can multiple tags type single block, multiple blocks can contribute .Rd file. job rd_section combine tags single top-level Rd section. tag generates rd_section combined previous section using merge(). default merge.rd_section() just concatenates values together (rd_section(x$type, c(x$value, y$value))); can override method need sophisticated behaviour. need define format() method convert object text .Rd file: can now try roclet_text(): Note namespacing ’re defining multiple new tags recommend using package name common prefix.","code":"#' @tip The mean of a logical vector is the proportion of `TRUE` values. #' @tip You can compute means of dates and date-times! \\section{Tips and tricks}{ \\itemize{ \\item The mean of a logical vector is the proportion of \\code{TRUE} values. \\item You can compute means of dates and date-times! } } roxy_tag_parse.roxy_tag_tip <- function(x) { tag_markdown(x) } text <- \" #' Title #' #' @tip The mean of a logical vector is the proportion of `TRUE` values. #' @tip You can compute means of dates and date-times! #' @md f <- function(x, y) { # ... } \" block <- parse_text(text)[[1]] block #> [:7] #> $tag #> [line: 2] @title 'Title' {parsed} #> [line: 4] @tip 'The mean of a logical vector is the proportion ...' {parsed} #> [line: 5] @tip 'You can compute means of dates and date-times!' {parsed} #> [line: 6] @md '' {parsed} #> [line: 7] @usage '' {parsed} #> [line: 7] @.formals '' {parsed} #> [line: 7] @backref '' {parsed} #> $call f <- function(x, y) { ... #> $object #> $topic f #> $alias f str(block$tags[[2]]) #> List of 5 #> $ file: chr \"\" #> $ line: int 4 #> $ tag : chr \"tip\" #> $ raw : chr \"The mean of a logical vector is the proportion of `TRUE` values.\" #> $ val : chr \"The mean of a logical vector is the proportion of \\\\code{TRUE} values.\" #> - attr(*, \"class\")= chr [1:2] \"roxy_tag_tip\" \"roxy_tag\" roxy_tag_rd.roxy_tag_tip <- function(x, base_path, env) { rd_section(\"tip\", x$val) } format.rd_section_tip <- function(x, ...) { paste0( \"\\\\section{Tips and tricks}{\\n\", \"\\\\itemize{\\n\", paste0(\" \\\\item \", x$value, \"\\n\", collapse = \"\"), \"}\\n\", \"}\\n\" ) } topic <- roc_proc_text(rd_roclet(), text)[[1]] topic$get_section(\"tip\") #> \\section{Tips and tricks}{ #> \\itemize{ #> \\item The mean of a logical vector is the proportion of \\code{TRUE} values. #> \\item You can compute means of dates and date-times! #> } #> } #>"},{"path":"https://roxygen2.r-lib.org/dev/articles/extending.html","id":"creating-a-new-roclet","dir":"Articles","previous_headings":"","what":"Creating a new roclet","title":"Extending roxygen2","text":"Creating new roclet usually two part process. First, define new tags roclet work . Second, define roclet tells roxygen process entire package.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/extending.html","id":"custom-tags","dir":"Articles","previous_headings":"Creating a new roclet","what":"Custom tags","title":"Extending roxygen2","text":"example make new @memo tag enable printing memos console roclet runs. choose @memo syntax: example: , first define parse method: check works parse_text():","code":"@memo [Headline] Description @memo [EFFICIENCY] Currently brute-force; find better algorithm. roxy_tag_parse.roxy_tag_memo <- function(x) { if (!grepl(\"^\\\\[.*\\\\].*$\", x$raw)) { roxy_tag_warning(x, \"Invalid memo format\") return() } parsed <- stringi::stri_match(str = x$raw, regex = \"\\\\[(.*)\\\\](.*)\")[1, ] x$val <- list( header = parsed[[2]], message = parsed[[3]] ) x } text <- \" #' @memo [TBI] Remember to implement this! #' @memo [API] Check best API f <- function(x, y) { # ... } \" block <- parse_text(text)[[1]] block #> [:4] #> $tag #> [line: 2] @memo '[TBI] Remember to implement this!' {parsed} #> [line: 3] @memo '[API] Check best API' {parsed} #> [line: 4] @usage '' {parsed} #> [line: 4] @.formals '' {parsed} #> [line: 4] @backref '' {parsed} #> $call f <- function(x, y) { ... #> $object #> $topic f #> $alias f str(block$tags[[1]]) #> List of 5 #> $ file: chr \"\" #> $ line: int 2 #> $ tag : chr \"memo\" #> $ raw : chr \"[TBI] Remember to implement this!\" #> $ val :List of 2 #> ..$ header : chr \"TBI\" #> ..$ message: chr \" Remember to implement this!\" #> - attr(*, \"class\")= chr [1:2] \"roxy_tag_memo\" \"roxy_tag\""},{"path":"https://roxygen2.r-lib.org/dev/articles/extending.html","id":"the-roclet","dir":"Articles","previous_headings":"Creating a new roclet","what":"The roclet","title":"Extending roxygen2","text":"Next, create constructor roclet, uses roclet(). memo roclet doesn’t options simple: give roclet behaviour, need define methods. two methods almost every roclet use: roclet_process() called list blocks, returns object choosing. roclet_output() produces side-effects (usually writing disk) using result roclet_process(). roclet, ’ll roclet_process() collect memo tags named list: roclet_output() just print screen: can test works using roc_proc_text():","code":"memo_roclet <- function() { roclet(\"memo\") } roclet_process.roclet_memo <- function(x, blocks, env, base_path) { results <- list() for (block in blocks) { tags <- block_get_tags(block, \"memo\") for (tag in tags) { msg <- paste0(\"[\", tag$file, \":\", tag$line, \"] \", tag$val$message) results[[tag$val$header]] <- c(results[[tag$val$header]], msg) } } results } roclet_output.roclet_memo <- function(x, results, base_path, ...) { for (header in names(results)) { messages <- results[[header]] cat(paste0(header, \": \", \"\\n\")) cat(paste0(\" * \", messages, \"\\n\", collapse = \"\")) } invisible(NULL) } results <- roc_proc_text(memo_roclet(), \" #' @memo [TBI] Remember to implement this! #' @memo [API] Check best API f <- function(x, y) { # ... } #' @memo [API] Consider passing z option g <- function(x, y) { # ... } \") roclet_output(memo_roclet(), results) #> TBI: #> * [:2] Remember to implement this! #> API: #> * [:3] Check best API #> * [:8] Consider passing z option"},{"path":"https://roxygen2.r-lib.org/dev/articles/extending.html","id":"adding-a-roclet-to-your-workflow","dir":"Articles","previous_headings":"","what":"Adding a roclet to your workflow","title":"Extending roxygen2","text":"use roclet developing package, call yourPackage::roclet function creates roclet, e.g. memo_roclet . can also add roclet target package’s DESCRIPTION file, like : Optionally, can add roclet package target package Suggests: dependency: don’t , help developers working target package.","code":"roxygen2::roxygenize(roclets = \"yourPackage::roclet\") Roxygen: list(roclets = c(\"collate\", \"rd\", \"namespace\", \"yourPackage::roclet\")) usethis::use_dev_package(\"yourPackage\", type = \"Suggests\", remote = \"yourGithubID/yourPackage\")"},{"path":"https://roxygen2.r-lib.org/dev/articles/index-crossref.html","id":"see-also","dir":"Articles","previous_headings":"","what":"See also","title":"Indexing and cross-references","text":"@seealso allows point useful resources, either web (using url) related functions (function link like [function_name()]). sum(), might look like:","code":"#' @seealso [prod()] for products, [cumsum()] for cumulative sums, and #' [colSums()]/[rowSums()] marginal sums over high-dimensional arrays."},{"path":"https://roxygen2.r-lib.org/dev/articles/index-crossref.html","id":"family","dir":"Articles","previous_headings":"","what":"Family","title":"Indexing and cross-references","text":"family related functions, can use @family {family} cross-reference function every member family. function can member multiple families. default @family {family}, generate see also text “{family}:”, @family name plural (.e., “model building helpers” “model building helper”). want override default title, can provide rd_family_title element list stored man/roxygen/meta.R:","code":"list( rd_family_title = list(aggregations = \"Aggregation functions\") )"},{"path":"https://roxygen2.r-lib.org/dev/articles/index-crossref.html","id":"references","dir":"Articles","previous_headings":"","what":"References","title":"Indexing and cross-references","text":"object ’re documenting connections scientific literature, use @reference provide citation.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/index-crossref.html","id":"aliases","dir":"Articles","previous_headings":"","what":"Aliases","title":"Indexing and cross-references","text":"? help() look topic aliases; ?foo find topic contains foo alias. roxygen2 generates default alias based object ’re documenting. can add additional aliases @aliases alias1 alias2 alias3 remove default alias @aliases NULL.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/index-crossref.html","id":"search","dir":"Articles","previous_headings":"","what":"Search","title":"Indexing and cross-references","text":"well looking aliases, help.search() ??? also look @title, @keywords, @concepts tags. @keywords adds standard keywords, must present file.path(R.home(\"doc\"), \"KEYWORDS\"). @concept adds arbitrary key words phrases. @concept contain single word phrase. Generally speaking, @keywords @concepts terribly useful people find documentation using Google, R’s built-search. ’s one exception: @keywords internal. ’s useful removes function documentation index; ’s useful functions aimed primarily developers, typical users package.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/index-crossref.html","id":"back-references","dir":"Articles","previous_headings":"","what":"Back references","title":"Indexing and cross-references","text":"original source location added comment second line generated .Rd file following form: roxygen2 tries capture locations documentation assembled. code generates R code Roxygen comments (e.g., Rcpp package), @backref tag provided. allows specifying “true” source documentation, substitute default list source files. Use one tag per source file:","code":"% Please edit documentation in ... #' @backref src/file.cpp #' @backref src/file.h"},{"path":"https://roxygen2.r-lib.org/dev/articles/namespace.html","id":"exports","dir":"Articles","previous_headings":"","what":"Exports","title":"Managing imports and exports","text":"order users use function1 package, must export . cases, can just use @export tag, roxygen2 automatically figure NAMESPACE directive (.e. export(), exportS3method(), exportClasses(), orexportMethods()) need. Note datasets never exported found NAMESPACE. Instead, datasets either automatically exported set LazyData: true DESCRIPTION, made available calling data() .","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/namespace.html","id":"functions","dir":"Articles","previous_headings":"Exports","what":"Functions","title":"Managing imports and exports","text":"function exported user facing; exported ’s internal use . export function, must also document , since people use , need careful later change function interface.","code":"#' Add two numbers together #' #' @param x,y A pair of numbers. #' @export add <- function(x, y) { x + y }"},{"path":"https://roxygen2.r-lib.org/dev/articles/namespace.html","id":"s3","dir":"Articles","previous_headings":"Exports","what":"S3","title":"Managing imports and exports","text":"S3 generic works like regular R function export following advice : want users call , export; otherwise, don’t. S3 methods regular functions special naming scheme, “export” works bit differently. S3 methods exported sense calling generic appropriate class call method; user can’t directly access method definition typing name. technically correctly term say method registered generics can find . must register, .e. @export, every S3 method regardless whether generic exported. roxygen2 warn forgotten. exporting method way, can use @exportS3Method NULL suppress warning. four options documenting S3 method: Don’t document ; ’s required, needed simple generics user won’t care details. method particularly complex many arguments generic , can document file. case, just document ’s function. can use @rdname document methods generic. good option ’s generic, ’re providing bunch methods different classes. can use @rdname document methods class. typically least appealing option different generics different arguments, leading cluttered potentially confusing page. Typically, write methods generics either defined current package package hard dependency2 package. Sometimes, however, want write method suggested dependency. case, @export work assumes generic included imported NAMESPACE. Instead, use @exportS3Method. use “delayed” method registration, means method registered suggested package loaded. use @exportS3Method must provide package generic name following format:","code":"#' Take an object to bizarro world #' #' @param x A vector. #' @export bizarro <- function(x, ...) { UseMethod(\"bizarro\") } #' @export bizarro.character <- function(x, ...) { letters <- strsplit(x, \"\") letters_rev <- lapply(letters, rev) vapply(letters_rev, paste, collapse = \"\", FUN.VALUE = character(1)) } #' Take an object to bizarro world #' #' @description #' This is an S3 generic. This package provides methods for the #' following classes: #' #' * `character`: reverses the order of the letters in each element of #' the vector. #' #' @param x A vector. #' @export bizarro <- function(x, ...) { UseMethod(\"bizarro\") } #' @export #' @rdname bizarro bizarro.character <- function(x, ...) { letters <- strsplit(x, \"\") letters_rev <- lapply(letters, rev) vapply(letters_rev, paste, collapse = \"\", FUN.VALUE = character(1)) } #' @exportS3Method pkg::generic generic.foo <- function(x, ...) { }"},{"path":"https://roxygen2.r-lib.org/dev/articles/namespace.html","id":"s4","dir":"Articles","previous_headings":"Exports","what":"S4","title":"Managing imports and exports","text":"Classes: export class object want others able extend . Generics: treat like function @export user facing. Methods: need @export method, generic lives another package. Unlike S3, must document S4 methods. method details often important, ’s common use @rdname put documentation unimportant methods single topic @keywords internal.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/namespace.html","id":"manual-exports","dir":"Articles","previous_headings":"Exports","what":"Manual exports","title":"Managing imports and exports","text":"@export automatically generate correct NAMESPACE directive, can use one tags exercise greater control: @export foo generates export(foo) @exportS3Method generic method generates S3method(generic, method) @exportClass foo generates exportClasses(foo) @exportMethod foo generates exportMethods(foo) @exportPattern foo generates exportPattern(foo) even specialised cases can use @rawNamespace code inserts code literally NAMESPACE. useful need conditional import export, e.g. need automate , @evalNamespace fun() evaluate fun() package environment insert results NAMESPACE. Note evalNamespace() run package environment, can generate exports, imports.","code":"# From dplyr: #' @rawNamespace import(vctrs, except = data_frame) # From backports: #' @rawNamespace if (getRversion() < \"4.0.0\") export(stopifnot)"},{"path":"https://roxygen2.r-lib.org/dev/articles/namespace.html","id":"imports","dir":"Articles","previous_headings":"","what":"Imports","title":"Managing imports and exports","text":"NAMESPACE also controls functions packages made available package.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/namespace.html","id":"functions-1","dir":"Articles","previous_headings":"Imports","what":"Functions","title":"Managing imports and exports","text":"using just functions another package, recommending adding package Imports: field DESCRIPTION file calling functions explicitly using ::, e.g., pkg::fun(). repetition package name becomes annoying can @importFrom drop ::: Imports affect every function package, ’s common collect central place, like {packagename}-package.R. automated usethis::use_import_from(). Note use NULL : must provide something roxygen2 document, use NULL place holder. possible, generally recommended import functions package @import package. risky import functions one package, might ok today, future packages might end function name, users get warning every time package loaded.","code":"my_function <- function(x, y) { pkg::fun(x) * y } #' @importFrom pkg fun my_function <- function(x, y) { fun(x) * y } #' @importFrom pkg fun1 fun2 #' @importFrom pkg2 fun3 #' @importFrom pkg3 fun4 NULL #> NULL"},{"path":"https://roxygen2.r-lib.org/dev/articles/namespace.html","id":"s3-1","dir":"Articles","previous_headings":"Imports","what":"S3","title":"Managing imports and exports","text":"S3 generics just functions, rules functions apply. S3 methods always accompany generic, long can access generic (either implicitly explicitly), methods also available. words, don’t need anything special S3 methods. long ’ve imported generic, methods also available.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/namespace.html","id":"s4-1","dir":"Articles","previous_headings":"Imports","what":"S4","title":"Managing imports and exports","text":"use classes defined another package, place @importClassesFrom package ClassA ClassB ... next classes inherit imported classes, next methods implement generic imported classes. use generics defined another package, place @importMethodsFrom package GenericA GenericB ... next methods use imported generics.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/namespace.html","id":"compiled-code","dir":"Articles","previous_headings":"Imports","what":"Compiled code","title":"Managing imports and exports","text":"import compiled code another package, use @useDynLib @useDynLib package imports compiled functions. @useDynLib package routinea routineb imports selected compiled functions. @useDynLib specification containing comma, e.g. @useDynLib mypackage, .registration = TRUE inserted NAMESPACE, e.g. useDynLib(mypackage, .registration = TRUE)","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"enabling-markdown-support","dir":"Articles","previous_headings":"","what":"Enabling markdown support","title":"(R)Markdown support","text":"turn Markdown support package, insert entry DESCRIPTION file package: use devtools/usethis, automatically inserted create new package. ’re updating existing package, recommend usethis::use_roxygen_md() modify DESCRIPTION prompt use roxygen2md package convert existing docs. needed, can also use @md @noMd turn markdown support documentation block. example roxygen chunk uses Markdown.","code":"Roxygen: list(markdown = TRUE) #' Use roxygen to document a package #' #' This function is a wrapper for the [roxygen2::roxygenize()] function from #' the roxygen2 package. See the documentation and vignettes of #' that package to learn how to use roxygen. #' #' @param pkg package description, can be path or package name. See #' [as.package()] for more information. #' @param clean,reload Deprecated. #' @inheritParams roxygen2::roxygenise #' @seealso [roxygen2::roxygenize()], `browseVignettes(\"roxygen2\")` #' @export"},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"basic-syntax","dir":"Articles","previous_headings":"","what":"Basic syntax","title":"(R)Markdown support","text":"roxygen uses commonmark package, based “CommonMark Reference Implementation”. See https://commonmark.org/help/ parser markdown language supports. important details described .","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"sections-and-subsections","dir":"Articles","previous_headings":"Basic syntax","what":"Sections and subsections","title":"(R)Markdown support","text":"usual Markdown heading markup creates sections subsections. Top level headings (e.g. # title) create sections \\section{} Rd tag. largely supersedes use older @section tag. Top-level headings can appear @description @details tags. Since @details can appear multiple times block, can always precede ‘#’ section @details, want put near end block, @return example: Top level sections placed fixed position manual page, parameters details, \\note{}, \\seealso{} \\examples{}. order roxygen block. Headings level two may appear inside roxygen tag formats lines text, e.g. @description, @details, @return, create subsections \\subsection{} Rd tag.","code":"#' @details #' Trim the leading and trailing whitespace from a character vector. #' #' @param x Character vector. #' @return Character vector, with the whitespace trimmed. #' #' @details # This will be a new section #' ... #' @details #' ## Subsection within details #' ### Sub-subsection #' ... text ..."},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"inline-formatting","dir":"Articles","previous_headings":"Basic syntax","what":"Inline formatting","title":"(R)Markdown support","text":"emphasis, put text asterisks underline characters. strong text, use two asterisks sides.","code":"#' @references #' Robert E Tarjan and Mihalis Yannakakis. (1984). Simple #' linear-time algorithms to test chordality of graphs, test acyclicity #' of hypergraphs, and selectively reduce acyclic hypergraphs. #' *SIAM Journal of Computation* **13**, 566-579. #' See `::is_falsy` for the definition of what is _falsy_ #' and what is _truthy_."},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"code","dir":"Articles","previous_headings":"Basic syntax","what":"Code","title":"(R)Markdown support","text":"Inline code supported via backticks. blocks code, put code triple backticks: can also include executable code chunks using usual knitr syntax. See details.","code":"#' @param ns Optionally, a named vector giving prefix-url pairs, as #' produced by `xml_ns`. If provided, all names will be explicitly #' qualified with the ns prefix, i.e. if the element `bar` is defined ... #' ``` #' pkg <- make_packages( #' foo1 = { f <- function() print(\"hello!\") ; d <- 1:10 }, #' foo2 = { f <- function() print(\"hello again!\") ; d <- 11:20 } #' ) #' foo1::f() #' foo2::f() #' foo1::d #' foo2::d #' dispose_packages(pkg) #' ```"},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"lists","dir":"Articles","previous_headings":"Basic syntax","what":"Lists","title":"(R)Markdown support","text":"Regular Markdown lists recognized converted \\enumerate{} \\itemize{} lists: Note leave empty line list. different Markdown parsers.","code":"#' There are two ways to use this function: #' 1. If its first argument is not named, then it returns a function #' that can be used to color strings. #' 1. If its first argument is named, then it also creates a #' style with the given name. This style can be used in #' `style`. One can still use the return value #' of the function, to create a style function. #' The style (the `...` argument) can be anything of the #' following: #' * An R color name, see `colors()`. #' * A 6- or 8-digit hexa color string, e.g. `#ff0000` means #' red. Transparency (alpha channel) values are ignored. #' * A one-column matrix with three rows for the red, green, #' and blue channels, as returned by [grDevices::col2rgb()]."},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"tables","dir":"Articles","previous_headings":"Basic syntax","what":"Tables","title":"(R)Markdown support","text":"Use GFM table formatting: default, columns left-aligned. Use colons generate right center aligned columns:","code":"| foo | bar | | --- | --- | | baz | bim | | left | center | right | | :--- | :----: | ----: | | 1 | 2 | 3 |"},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"links","dir":"Articles","previous_headings":"Basic syntax","what":"Links","title":"(R)Markdown support","text":"Markdown hyperlinks work usual: URLs inside angle brackets also automatically converted hyperlinks:","code":"#' See more about the Markdown markup at the #' [Commonmark web site](http://commonmark.org/help) #' The main R web site is at ."},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"images","dir":"Articles","previous_headings":"Basic syntax","what":"Images","title":"(R)Markdown support","text":"Markdown syntax inline images works. image files must man/figures directory:","code":"#' Here is an example plot: #' ![](example-plot.jpg \"Example Plot Title\")"},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"function-links","dir":"Articles","previous_headings":"","what":"Function links","title":"(R)Markdown support","text":"Markdown notation can also used create links help topics. two basic forms: [topic]: link text automatically generated topic. [text][topic]: supply link text.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"default-link-text","dir":"Articles","previous_headings":"Function links","what":"Default link text","title":"(R)Markdown support","text":"First explore simplest form: [ref]. presence trailing parentheses, e.g., [func()], signals target func function, causes two things happen: link text func() automatically typeset code. parentheses stripped derived Rd link target.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"custom-link-text","dir":"Articles","previous_headings":"Function links","what":"Custom link text","title":"(R)Markdown support","text":"Use second form [text][ref] link topic specified ref, text link text.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"operators","dir":"Articles","previous_headings":"Function links","what":"Operators","title":"(R)Markdown support","text":"Links operators objects contain special characters currently work. link (e.g.) %>% operator magrittr package, instead [magrittr::%>%], need use Rd notation: \\code{\\link[magrittr]{\\%>\\%}}.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"code-chunks","dir":"Articles","previous_headings":"","what":"Code chunks","title":"(R)Markdown support","text":"can insert executable code ```{r}, just like knitr documents. example: becomes: code run every time call roxygenize() (devtools::document()) generate Rd files. potentially makes roxygenize() (much) slower. Either avoid expensive computations, turn knitr caching cache = TRUE. Make sure omit cache package usethis::use_build_ignore(). Note knitr call appropriate print() (available) knitr::knit_print() method result. may generate markdown supported roxygen2. needed, override automatic methods R calls return markdown character vector, wrapped knitr::asis_output().","code":"#' @title Title #' @details Details #' ```{r lorem} #' 1+1 #' ``` #' @md foo <- function() NULL % Generated by roxygen2: do not edit by hand % Please edit documentation in ./ \\name{foo} \\alias{foo} \\title{Title} \\usage{ foo() } \\description{ Title } \\details{ Details \\if{html}{\\out{
}}\\preformatted{1+1 #> [1] 2 }\\if{html}{\\out{<\/div>}} }"},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"chunk-options","dir":"Articles","previous_headings":"Code chunks","what":"Chunk options","title":"(R)Markdown support","text":"Code blocks support knitr chunk options, e.g. keep output several expressions together, can specify results=\"hold\": knitr chunk options reset start every code block, want change , ’ll specify every chunk. currently error, fig.path, fig.process, comment, collapse. Alternatively, can set knitr_chunk_options option override defaults, add new chunk options used whole package. See ?load_options specifying roxygen2 options.","code":"#' ```{r results=\"hold\"} #' names(mtcars) #' nrow(mtcars) #' ```"},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"images-1","dir":"Articles","previous_headings":"Code chunks","what":"Images","title":"(R)Markdown support","text":"Plots create .png files man/figures directory file names coming chunk name. aware plots can quickly increase size package leading challenges CRAN submission. default roxygen2 includes PDF images PDF manual, SVG images HTML manual. want avoid restriction, set restrict_image_formats roxygen2 option FALSE, see ?load_options.","code":"#' ```{r iris-pairs-plot} #' pairs(iris[1:4], main = \"Anderson's Iris Data -- 3 species\", #' pch = 21, bg = c(\"red\", \"green3\", \"blue\")[unclass(iris$Species)]) #' ```"},{"path":[]},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"some-rd-tags-cant-contain-markdown","dir":"Articles","previous_headings":"Possible problems","what":"Some Rd tags can’t contain markdown","title":"(R)Markdown support","text":"mixing Rd Markdown notation, Rd tags may contain Markdown markup, ones can : \\acronym, \\code, \\command, \\CRANpkg, \\deqn, \\doi, \\dontrun, \\dontshow, \\donttest, \\email, \\env, \\eqn, \\figure, \\file, \\, \\ifelse, \\kbd, \\link, \\linkS4class, \\method, \\mjeqn, \\mjdeqn, \\mjseqn, \\mjsdeqn, \\mjteqn, \\mjtdeqn, \\newcommand, \\option, \\, \\packageAuthor, \\packageDescription, \\packageDESCRIPTION, \\packageIndices, \\packageMaintainer, \\packageTitle, \\pkg, \\PR, \\preformatted, \\renewcommand, \\S3method, \\S4method, \\samp, \\special, \\testonly, \\url, \\var, \\verb.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"mixing-markdown-and-rd-markup","dir":"Articles","previous_headings":"Possible problems","what":"Mixing Markdown and Rd markup","title":"(R)Markdown support","text":"Note turning Markdown turn standard Rd syntax. suggest use regular Rd tags Markdown roxygen chunk necessary. two parsers occasionally interact, Markdown parser can pick reformat Rd syntax, causing error, corrupted manuals.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"leading-white-space","dir":"Articles","previous_headings":"Possible problems","what":"Leading white space","title":"(R)Markdown support","text":"Leading white space interpreted commonmark parser, ignored Rd parser (except \\preformatted{}). Make sure include leading white space intentionally, example, nested lists.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-formatting.html","id":"spurious-lists","dir":"Articles","previous_headings":"Possible problems","what":"Spurious lists","title":"(R)Markdown support","text":"commonmark parser require empty line lists, might lead unintended lists line starts number followed dot, asterisk followed white space:","code":"#' You can see more about this topic in the book cited below, on page #' 42. Clearly, the numbered list that starts here is not intentional."},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-other.html","id":"datasets","dir":"Articles","previous_headings":"","what":"Datasets","title":"Documenting other objects","text":"Datasets stored data/, regular R objects package. means need document slightly different way: instead documenting data directly, quote dataset’s name. Note use two additional tags particularly useful documenting data: @format, gives overview structure dataset. include definition list describes variable. ’s currently way generate Markdown, one places ’ll need Rd markup directly. @source got data form, often URL.","code":"#' Prices of over 50,000 round cut diamonds #' #' A dataset containing the prices and other attributes of almost 54,000 #' diamonds. The variables are as follows: #' #' @format A data frame with 53940 rows and 10 variables: #' \\describe{ #' \\item{price}{price in US dollars ($326--$18,823)} #' \\item{carat}{weight of the diamond (0.2--5.01)} #' \\item{cut}{quality of the cut (Fair, Good, Very Good, Premium, Ideal)} #' \\item{color}{diamond colour, from D (best) to J (worst)} #' \\item{clarity}{a measurement of how clear the diamond is (I1 (worst), SI2, #' SI1, VS2, VS1, VVS2, VVS1, IF (best))} #' \\item{x}{length in mm (0--10.74)} #' \\item{y}{width in mm (0--58.9)} #' \\item{z}{depth in mm (0--31.8)} #' \\item{depth}{total depth percentage = z / mean(x, y) = 2 * z / (x + y) (43--79)} #' \\item{table}{width of top of diamond relative to widest point (43--95)} #' } #' #' @source {ggplot2} tidyverse R package."},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-other.html","id":"packages","dir":"Articles","previous_headings":"","what":"Packages","title":"Documenting other objects","text":"well documenting every object inside package, can also document package documenting special sentinel \"_PACKAGE\". automatically includes information parsed DESCRIPTION, including title, description, list authors, useful URLs. recommend placing package documentation {pkgname}-package.R, @keywords internal. Use usethis::use_package_doc() set automatically. ’s example: Package documentation good place put # Package options documents options used package. notes: default, aliases added ?pkgname package?pkgname find package help. ’s existing function called pkgname, use @aliases {pkgname}-package NULL override default. Use @references point published material package users might find helpful.","code":"#' @keywords internal \"_PACKAGE\""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-other.html","id":"s3","dir":"Articles","previous_headings":"","what":"S3","title":"Documenting other objects","text":"S3 generics regular functions, document . necessary, include section provides additional details developers implementing methods. S3 classes formal definition, document constructor. choice whether document S3 methods. Generally, ’s necessary document straightforward methods common generics like print(). (, however, always @export S3 methods). method complicated, document setting @rdname @describeIn. complicated methods, might document file (.e. @rdname generic.class; simpler methods might document generic (.e. @describeIn generic). Learn tags vignette(\"reuse\"). Generally, roxygen2 automatically figure generic method belongs , need use @method ambiguity. example, .equal.data.frame() equal.data.frame method (), data.frame method .equal()?. happens , disambiguate (e.g.) @method .equal data.frame.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-other.html","id":"s4","dir":"Articles","previous_headings":"","what":"S4","title":"Documenting other objects","text":"S4 generics also functions, document . Document S4 classes adding roxygen block setClass(). Use @slot document slots class. ’s simple example: S4 methods little complicated. Unlike S3 methods, S4 methods must documented. can document three places: class. appropriate corresponding generic uses single dispatch created class. generic. appropriate generic uses multiple dispatches control . file. appropriate method complex. either two options don’t apply. Use either @rdname @describeIn control method documentation goes. See next section details.","code":"#' An S4 class to represent a bank account #' #' @slot balance A length-one numeric vector Account <- setClass(\"Account\", slots = list(balance = \"numeric\") )"},{"path":"https://roxygen2.r-lib.org/dev/articles/rd-other.html","id":"r6","dir":"Articles","previous_headings":"","what":"R6","title":"Documenting other objects","text":"R6 methods can documented -line, .e. method’s documentation comments come right definition method. Method documentation can use @description, @details, @param, @return @examples tags. used create subsection method, within separate ‘Methods’ section. roxygen comment lines method documentation must appear tag. @param tags appear class definition automatically inherited methods, needed. R6 fields active bindings can make use @field tag. documentation also -line. roxygen2 checks public methods, public fields, active bindings method arguments documented, issues warnings otherwise. turn special handling R6 classes go back roxygen2 6.x.x behavior, use r6 = FALSE option DESCRIPTION, Roxygen entry: Roxygen: list(r6 = FALSE). roxygen2 automatically generates additional sections R6 class: section information superclass(es) class, links. HTML includes list inherited methods, links. ‘Examples’ section contains class method examples. section run R CMD check, method examples must work without errors. example R6 tutorial:","code":"#' R6 Class Representing a Person #' #' @description #' A person has a name and a hair color. #' #' @details #' A person can also greet you. Person <- R6::R6Class(\"Person\", public = list( #' @field name First or full name of the person. name = NULL, #' @field hair Hair color of the person. hair = NULL, #' @description #' Create a new person object. #' @param name Name. #' @param hair Hair color. #' @return A new `Person` object. initialize = function(name = NA, hair = NA) { self$name <- name self$hair <- hair self$greet() }, #' @description #' Change hair color. #' @param val New hair color. #' @examples #' P <- Person(\"Ann\", \"black\") #' P$hair #' P$set_hair(\"red\") #' P$hair set_hair = function(val) { self$hair <- val }, #' @description #' Say hi. greet = function() { cat(paste0(\"Hello, my name is \", self$name, \".\\n\")) } ) )"},{"path":"https://roxygen2.r-lib.org/dev/articles/rd.html","id":"basics","dir":"Articles","previous_headings":"","what":"Basics","title":"Documenting functions","text":"roxygen block sequence lines starting #' (optionally preceded white space). first lines block called introduction forms title, description, details, described . introduction continues first tag. Tags start @, like @details @param. Tags must appear beginning line content extends start next tag end block. Text within description tags can formatted using Markdown Rd commands; see vignette(\"rd-formatting\") details. block ends hits R code, usually function object assignment. Blocks ignore empty lines, including lines made non-roxygen comments. need separate two blocks, use NULL. want use roxygen2 documentation tags without generating .Rd file, can use @noRd suppress file generation given topic. useful want use roxygen2 conventions documenting internal function; people reading source doc able read docs.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd.html","id":"the-introduction","dir":"Articles","previous_headings":"","what":"The introduction","title":"Documenting functions","text":"documentation block starts text defines title, description, details. ’s example showing documentation sum() might look like written roxygen: introductory block broken follows: first sentence title: ’s see look help(package = mypackage) shown top help file. generally fit one line, written sentence case, end full stop. second paragraph description: comes first documentation briefly describe function . third subsequent paragraphs go details: (often long) section comes argument description provide important details function operates. details optional. can also use explicit @title, @description, @details tags. unnecessary unless want multi-paragraph description, bulleted list, exotic structure.","code":"#' Sum of vector elements #' #' `sum` returns the sum of all the values present in its arguments. #' #' This is a generic function: methods can be defined for it directly #' or via the [Summary()] group generic. For this to work properly, #' the arguments `...` should be unnamed, and dispatch is on the #' first argument. sum <- function(..., na.rm = TRUE) {} #' Sum of vector elements #' #' @description #' `sum` returns the sum of all the values present in its arguments. #' #' @details #' This is a generic function: methods can be defined for it directly #' or via the [Summary()] group generic. For this to work properly, #' the arguments `...` should be unnamed, and dispatch is on the #' first argument."},{"path":"https://roxygen2.r-lib.org/dev/articles/rd.html","id":"functions","dir":"Articles","previous_headings":"","what":"Functions","title":"Documenting functions","text":"Functions commonly documented objects. Functions require three tags: @param, @returns, @examples.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd.html","id":"inputs","dir":"Articles","previous_headings":"Functions","what":"Inputs","title":"Documenting functions","text":"Use @param name description describe input function. description provide succinct summary parameter type (e.g. string, numeric vector), obvious name, parameter . description sentence start capital letter end full stop. can span multiple lines (even paragraphs) necessary. parameters must documented. two arguments tightly coupled, can document one place separating names commas (spaces). example, document x y, can say @param x,y Numeric vectors.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd.html","id":"outputs","dir":"Articles","previous_headings":"Functions","what":"Outputs","title":"Documenting functions","text":"@returns description describes output function. Briefly describe type/shape output, details. functions must documented return value initial CRAN submission.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/rd.html","id":"examples","dir":"Articles","previous_headings":"Functions","what":"Examples","title":"Documenting functions","text":"@examples provides executable R code showing use function practice. important part documentation many people look examples reading anything. Example code must work without errors run automatically part R CMD check. purpose illustration, ’s often useful include code causes error. can wrapping code try() using \\dontrun{} exclude executed example code. finer control, can use @examplesIf: generates way, code evaluating whether example can run shown users reading help, still prevents R CMD check failures. Instead including examples directly documentation, can put separate files use @example path/relative//package/root insert documentation. functions must examples initial CRAN submission.","code":"#' @examplesIf interactive() #' browseURL(\"https://roxygen2.r-lib.org\") \\examples{ \\dontshow{if (interactive() (if (getRversion() >= \"3.4\") withAutoprint else force)(\\{ # examplesIf} gh_organizations(since = 42) \\dontshow{\\}) # examplesIf} }"},{"path":"https://roxygen2.r-lib.org/dev/articles/rd.html","id":"usage","dir":"Articles","previous_headings":"Functions","what":"Usage","title":"Documenting functions","text":"case, function usage (appears beneath description generates docs) automatically derived function specification. cases , please file issue use @usage override default want. want suppress usage altogether (sometimes useful internal deprecated functions), can use @usage NULL.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"multiple-functions-in-the-same-topic","dir":"Articles","previous_headings":"","what":"Multiple functions in the same topic","title":"Reusing documentation","text":"can document multiple functions file using either @rdname @describeIn tag. ’s technique best used care: documenting many functions one place leads confusion. Use functions (similar) arguments.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"rdname","dir":"Articles","previous_headings":"Multiple functions in the same topic","what":"@rdname","title":"Reusing documentation","text":"Use @rdname 1 include multiple functions page. Tags (e.g. @title, @description, @examples) combined, across blocks often yields text hard understand. recommend make one block contains title, description, common parameters, examples , document individual parameters blocks. two basic ways . can create standalone documentation block add functions . typically works best family related functions want link family functions (.e. trig examples ). Alternatively, can add docs existing function. tends work better “primary” function variants helpers.","code":"#' Trigonometric approximations #' @param x Input, in radians. #' @name trig NULL #> NULL #' @rdname trig #' @export sin_ish <- function(x) x - x^3 / 6 #' @rdname trig #' @export cos_ish <- function(x) 1 - x^2 / 2 #' @rdname trig #' @export tan_ish <- function(x) x + x^3 / 3 #' Logarithms #' #' @param x A numeric vector #' @export log <- function(x, base) ... #' @rdname log #' @export log2 <- function(x) log(x, 2) #' @rdname log #' @export ln <- function(x) log(x, exp(1))"},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"describein","dir":"Articles","previous_headings":"Multiple functions in the same topic","what":"@describeIn","title":"Reusing documentation","text":"alternative @rdname @describeIn. slightly different syntax well topic name, also provide brief description function, like @describein topic one sentence description. primary difference @rdname @describeIn, @describeIn creates new section containing bulleted list function, along description. uses number heuristics determine heading section, depending ’re documenting related functions, methods generic, methods class. general, longer recommend @describeIn don’t think heuristics uses good thoughtful hand-crafted summary. ’re currently using @describeIn, can general replace @rdname, long give thought multiple-function @description.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"order-of-includes","dir":"Articles","previous_headings":"Multiple functions in the same topic","what":"Order of includes","title":"Reusing documentation","text":"default, roxygen blocks processed order appear file. ’re combining multiple files, can sometimes cause function usage appear suboptimal order. can override default ordering @order. example, following block place times first arith.Rd 1 comes 2.","code":"#' @rdname arith #' @order 2 add <- function(x, y) x + y #' @rdname arith #' @order 1 times <- function(x, y) x * y"},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"automatically-copy-tags","dir":"Articles","previous_headings":"","what":"Automatically copy tags","title":"Reusing documentation","text":"two functions share similarities different complex enough don’t want document single file, can use one four @inherit tags automatically copy various components another topic: @inheritParams foo copy @param contents foo. @inherit foo copy supported components foo. @inheritSection foo {Section title} copy @section {Section title} section foo. @inheritDotParams foo generate documentation … copying documentation foo()’s arguments. think “inheritance” rather just copying, anything inherit can overridden specific definition documentation. applies particularly @inheritParams allows copy documentation parameters documenting others directly. ’ll focus first.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"parameters","dir":"Articles","previous_headings":"Automatically copy tags","what":"Parameters","title":"Reusing documentation","text":"oldest, frequently used, inherits tag @inheritParams. ’s particularly useful multiple functions use argument name task, can document argument , inherit docs elsewhere. example, take dplyr functions arrange(), mutate(), summarise() argument called .data. arrange() documented like : mutate() summarise() don’t need provide @param .data can instead inherit documentation arrange(): wrote wouldn’t quite right mutate() summarise() also inherit documentation ..., different interpretation functions. , example, mutate() provides definition ...: Note documentation arguments names inherited. example, arrange() also .by_group argument. Since function dplyr argument name, documentation never inherited.","code":"#' @param .data A data frame, data frame extension (e.g. a tibble), or a #' lazy data frame (e.g. from dbplyr or dtplyr). See *Methods*, below, for #' more details. #' @param ... <[`data-masking`][rlang::args_data_masking]> Variables, or #' functions of variables. Use [desc()] to sort a variable in descending #' order. arrange <- function(.data, ...) {} #' @inheritParams arrange mutate <- function(.data, ...) {} #' @inheritParams arrange summarise <- function(.data, ...) {} #' @inheritParams arrange #' @param ... <[`data-masking`][rlang::args_data_masking]> Name-value pairs. #' The name gives the name of the column in the output. #' #' The value can be: #' #' * A vector of length 1, which will be recycled to the correct length. #' * A vector the same length as the current group (or the whole data frame #' if ungrouped). #' * `NULL`, to remove the column. #' * A data frame or tibble, to create multiple columns in the output. mutate <- function(.data, ...) {}"},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"multiple-parameters","dir":"Articles","previous_headings":"Automatically copy tags","what":"Multiple parameters","title":"Reusing documentation","text":"Sometimes document two () tightly coupled parameters together. example, dplyr::left_join() : joint parameter documentation inherited, ’s nothing, .e. function @inheritParams left_join inherit documentation x y x y arguments neither documented inheriting function.","code":"#' @param x,y A pair of data frames, data frame extensions (e.g. a tibble), or #' lazy data frames (e.g. from dbplyr or dtplyr). See *Methods*, below, for #' more details."},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"the-dot-prefix","dir":"Articles","previous_headings":"Automatically copy tags","what":"The dot prefix","title":"Reusing documentation","text":"Many tidyverse functions accept named arguments ... also use . prefix arguments. reduces risk argument going wrong place. example, dplyr::mutate() ., .keep, ., .arguments, didn’t prefix, wouldn’t able create new variables called , keep, , . call pattern dot prefix. means argument meaning can come one two forms: without .. @inheritParams knows common pattern ignores . prefix matching argument name. words, .x inherit documentation x, x inherit documentation .x.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"inheriting-other-components","dir":"Articles","previous_headings":"Automatically copy tags","what":"Inheriting other components","title":"Reusing documentation","text":"can use @inherits foo inherit documentation every supported tag another topic. Currently, @inherits supports inheriting following tags: params, return, title, description, details, seealso, sections, references, examples, author, source, note, format. supplying space separated list components function name, can also choose inherit selected components. example, @inherit foo returns just inherit @returns tag, @inherit foo seealso source inherit @seealso @source tags. @inherit foo sections inherit every @section tag (can also specified markdown using top-level heading spec, #). inherit specific section another function, use @inheritSection foo Section title. example, “adverbs” purrr use #' @inheritSection safely Adverbs inherit standard section provides advice using adverb package code.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"documenting----","dir":"Articles","previous_headings":"Automatically copy tags","what":"Documenting ...","title":"Reusing documentation","text":"function passes ... another function, can useful inline documentation common arguments. technique inspired documentation plot(), ... can take graphical parameter; ?plot describes common arguments don’t look ?par. @inheritDotParams two components: function inherit arguments inherit. Since ’ll typically want document important arguments, @inheritDotParams comes flexible specification argument selection inspired dplyr::select(): @inheritDotParams foo takes parameters foo(). @inheritDotParams foo b e:h takes parameters , b, parameters e h. @inheritDotParams foo -x -y takes parameters except x y.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"inheriting-from-other-packages","dir":"Articles","previous_headings":"Automatically copy tags","what":"Inheriting from other packages","title":"Reusing documentation","text":"’s common inherit documentation topics within current package, roxygen2 also supports inheriting documentation packages using package::function syntax, e.g.: @inheritParams package::function @inherit package::function @inheritSection package::function Section title @inheritDotParams package::function inheriting documentation another package bear mind ’re now taking fairly strong dependency external package, ensure every developer produces documentation ’ll need make sure version package installed. package changes name topic section, documentation require update. reasons, technique best used sparingly.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"inline-code","dir":"Articles","previous_headings":"","what":"Inline code","title":"Reusing documentation","text":"insert code inline, enclose `r `. Roxygen interpret rest text within backticks R code evaluate , replace backtick expression value. ’s simple example: equivalent writing: resulting text, together whole tag interpreted markdown, usual. means can use R dynamically write markdown. example defined function package: write: result equivalent writing following hand: powerful technique reducing duplication can flexibly parameterise function however best meets needs. Note evaluation environment deliberately child package ’re documenting can call internal functions.","code":"#' Title `r 1 + 1` #' #' Description `r 2 + 2` foo <- function() NULL #' Title 2 #' #' Description 4 foo <- function() NULL alphabet <- function(n) { paste0(\"`\", letters[1:n], \"`\", collapse = \", \") } #' Title #' #' @param x A string. Must be one of `r alphabet(5)` foo <- function(x) NULL #' Title #' #' @param x A string. Must be one of `a`, `b`, `c`, `d`, `e` foo <- function(x) NULL"},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"child-documents","dir":"Articles","previous_headings":"","what":"Child documents","title":"Reusing documentation","text":"can use .Rmd .md document documentation, README.Rmd, vignettes using child documents: included Rmd file can roxygen Markdown-style links help topics. E.g. [roxygen2::roxygenize()] link manual page roxygenize function roxygen2. See vignette(\"rd-formatting\") details. Rmd file contains roxygen (Markdown-style) links help topics, care needed, links work Rmd files default. workaround specify external HTML links . external locations used manual instead always links help topics manual. Example: example link supplied URLs HTML / Markdown files link roxygenize help topic manual. Note add external link targets like , roxygen emit warning link references defined multiple times (externally, help topic). warning originates Pandoc, harmless.","code":"```{r child = \"common.Rmd\"} ``` See also the [roxygen2::roxygenize()] function. [roxygen2::roxygenize()]: https://roxygen2.r-lib.org/reference/roxygenize.html"},{"path":"https://roxygen2.r-lib.org/dev/articles/reuse.html","id":"superseded","dir":"Articles","previous_headings":"","what":"Superseded","title":"Reusing documentation","text":"years, experimented number ways reduce duplication across documentation files. number now superseded recommend changing use techniques described : Instead @includeRmd man/rmd/example.Rmd, use child document. Instead @eval @evalRd, use inline R code. Instead @template @templateVars write function call inline R code. Inline R markdown can generate markdown text within tag principle less flexible @eval/@evalRd/@template. However, experience revealed generating multiple tags tends rather inflexible, often end refactoring smaller pieces don’t believe reflects real loss functionality.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/roxygen2.html","id":"learn-more","dir":"Articles","previous_headings":"","what":"Learn more","title":"Get started with roxygen2","text":"vignette provides high-level description roxygen2 overall workflow ’ll use . vignettes provide detail important individual components: Start vignette(\"rd\") learn document functions roxygen2. vignette(\"rd-\") discusses document things like datasets, package , various pieces used R’s OOP systems. vignette(\"rd-formatting\") gives details roxygen2’s rmarkdown support. vignette(\"reuse\") demonstrates tools available reuse documentation multiple places. vignette(\"namespace\") describes generate NAMESPACE file, namespacing works R, can use roxygen2 specific package needs supplies.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/roxygen2.html","id":"running-roxygen","dir":"Articles","previous_headings":"","what":"Running roxygen","title":"Get started with roxygen2","text":"three main ways run roxygen: roxygen2::roxygenise(). devtools::document(). Ctrl + Shift + D, ’re using RStudio. can mix handwritten Rd roxygen2; roxygen2 never overwrite file didn’t create.","code":""},{"path":"https://roxygen2.r-lib.org/dev/articles/roxygen2.html","id":"basic-process","dir":"Articles","previous_headings":"","what":"Basic process","title":"Get started with roxygen2","text":"three steps transformation roxygen comments source file human readable documentation: add roxygen comments source file. roxygen2::roxygenise() converts roxygen comments .Rd files. R converts .Rd files human readable documentation. process starts add specially formatted roxygen comments source file. Roxygen comments start #' can continue use regular comments purposes. example , generate man/add.Rd looks like: Rd files special file format loosely based LaTeX. can read Rd format R extensions manual. roxygen2, reasons know Rd files, ’ll avoid discussing much possible, focusing instead need know roxygen2. use ?x, help(\"x\") example(\"x\") R looks Rd file containing \\alias{x}. parses file, converts HTML displays . functions look Rd file installed packages. isn’t useful package development, want use .Rd files source package. reason, recommend use roxygen2 conjunction devtools: devtools::load_all() automatically adds shims ? friends look development package.","code":"#' Add together two numbers #' #' @param x A number. #' @param y A number. #' @return A number. #' @examples #' add(1, 1) #' add(10, 1) add <- function(x, y) { x + y } % Generated by roxygen2: do not edit by hand % Please edit documentation in ./ \\name{add} \\alias{add} \\title{Add together two numbers} \\usage{ add(x, y) } \\arguments{ \\item{x}{A number.} \\item{y}{A number.} } \\value{ A number. } \\description{ Add together two numbers } \\examples{ add(1, 1) add(10, 1) }"},{"path":"https://roxygen2.r-lib.org/dev/authors.html","id":null,"dir":"","previous_headings":"","what":"Authors","title":"Authors and Citation","text":"Hadley Wickham. Author, maintainer, copyright holder. Peter Danenberg. Author, copyright holder. Gábor Csárdi. Author. Manuel Eugster. Author, copyright holder. . Copyright holder, funder.","code":""},{"path":"https://roxygen2.r-lib.org/dev/authors.html","id":"citation","dir":"","previous_headings":"","what":"Citation","title":"Authors and Citation","text":"Wickham H, Danenberg P, Csárdi G, Eugster M (2024). roxygen2: -Line Documentation R. R package version 7.3.0.9000, https://github.com/r-lib/roxygen2, https://roxygen2.r-lib.org/.","code":"@Manual{, title = {roxygen2: In-Line Documentation for R}, author = {Hadley Wickham and Peter Danenberg and Gábor Csárdi and Manuel Eugster}, year = {2024}, note = {R package version 7.3.0.9000, https://github.com/r-lib/roxygen2}, url = {https://roxygen2.r-lib.org/}, }"},{"path":"https://roxygen2.r-lib.org/dev/index.html","id":"roxygen2-","dir":"","previous_headings":"","what":"In-Line Documentation for R","title":"In-Line Documentation for R","text":"premise roxygen2 simple: describe functions comments next definitions roxygen2 process source code comments automatically generate .Rd files man/, NAMESPACE, , needed, Collate field DESCRIPTION.","code":""},{"path":"https://roxygen2.r-lib.org/dev/index.html","id":"installation","dir":"","previous_headings":"","what":"Installation","title":"In-Line Documentation for R","text":"","code":"# Install roxygen2 from CRAN install.packages(\"roxygen2\") # Or the development version from GitHub: # install.packages(\"pak\") pak::pak(\"r-lib/roxygen2\")"},{"path":"https://roxygen2.r-lib.org/dev/index.html","id":"usage","dir":"","previous_headings":"","what":"Usage","title":"In-Line Documentation for R","text":"premise roxygen2 simple: describe functions comments next definitions roxygen2 process source code comments produce Rd files man/ directory. ’s simple example stringr package: roxygenise() (devtools::document()) package comments automatically transformed .Rd R uses generate documentation see type ?str_length.","code":"#' The length of a string #' #' Technically this returns the number of \"code points\", in a string. One #' code point usually corresponds to one character, but not always. For example, #' an u with a umlaut might be represented as a single character or as the #' combination a u and an umlaut. #' #' @inheritParams str_detect #' @return A numeric vector giving number of characters (code points) in each #' element of the character vector. Missing string have missing length. #' @seealso [stringi::stri_length()] which this function wraps. #' @export #' @examples #' str_length(letters) #' str_length(NA) #' str_length(factor(\"abc\")) #' str_length(c(\"i\", \"like\", \"programming\", NA)) str_length <- function(string) { }"},{"path":"https://roxygen2.r-lib.org/dev/index.html","id":"learn-more","dir":"","previous_headings":"","what":"Learn more","title":"In-Line Documentation for R","text":"get started, first read vignette(\"roxygen2\"). read specific package component want generate: Start vignette(\"rd\") learn document functions roxygen2. vignette(\"rd-\") discusses document things like datasets, package , various pieces used R’s OOP systems. vignette(\"rd-formatting\") gives details roxygen2’s rmarkdown support. vignette(\"reuse\") demonstrates tools available reuse documentation multiple places. vignette(\"namespace\") describes generate NAMESPACE file, namespacing works R, can use roxygen2 specific package needs supplies. Collate field DESCRIPTION, see ?update_collate().","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":null,"dir":"Reference","previous_headings":"","what":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"RoxyTopic object corresponds generated .Rd file.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"public-fields","dir":"Reference","previous_headings":"","what":"Public fields","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"sections Named list sections. item must rd_section() object. filename Path .Rd file generate.","code":""},{"path":[]},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"public-methods","dir":"Reference","previous_headings":"","what":"Public methods","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"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()","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"method-format-","dir":"Reference","previous_headings":"","what":"Method format()","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Format .Rd file. considers sections particular order, even though Rd tools reorder .","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"usage","dir":"Reference","previous_headings":"","what":"Usage","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"","code":"RoxyTopic$format(...)"},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"... Passed format() methods rd_section() objects, sections.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"returns","dir":"Reference","previous_headings":"","what":"Returns","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Character string.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"method-is-valid-","dir":"Reference","previous_headings":"","what":"Method is_valid()","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Check .Rd file valid","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"usage-1","dir":"Reference","previous_headings":"","what":"Usage","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"","code":"RoxyTopic$is_valid()"},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"returns-1","dir":"Reference","previous_headings":"","what":"Returns","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Logical flag, TRUE valid .Rd files","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"method-has-section-","dir":"Reference","previous_headings":"","what":"Method has_section()","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Check .Rd file certain section.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"usage-2","dir":"Reference","previous_headings":"","what":"Usage","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"","code":"RoxyTopic$has_section(type)"},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"arguments-1","dir":"Reference","previous_headings":"","what":"Arguments","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"type Section type, character scalar.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"returns-2","dir":"Reference","previous_headings":"","what":"Returns","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Logical flag.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"method-get-section-","dir":"Reference","previous_headings":"","what":"Method get_section()","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Query section.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"usage-3","dir":"Reference","previous_headings":"","what":"Usage","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"","code":"RoxyTopic$get_section(type)"},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"arguments-2","dir":"Reference","previous_headings":"","what":"Arguments","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"type Section type, character scalar.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"returns-3","dir":"Reference","previous_headings":"","what":"Returns","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"rd_section object representing section, NULL topic section.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"method-get-value-","dir":"Reference","previous_headings":"","what":"Method get_value()","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Query value section. value rd_section object.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"usage-4","dir":"Reference","previous_headings":"","what":"Usage","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"","code":"RoxyTopic$get_value(type)"},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"arguments-3","dir":"Reference","previous_headings":"","what":"Arguments","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"type Section type, character scalar.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"returns-4","dir":"Reference","previous_headings":"","what":"Returns","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Value.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"method-get-rd-","dir":"Reference","previous_headings":"","what":"Method get_rd()","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Get Rd code section.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"usage-5","dir":"Reference","previous_headings":"","what":"Usage","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"","code":"RoxyTopic$get_rd(type)"},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"arguments-4","dir":"Reference","previous_headings":"","what":"Arguments","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"type Section type, character scalar.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"returns-5","dir":"Reference","previous_headings":"","what":"Returns","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Character vector, one element per line.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"method-get-name-","dir":"Reference","previous_headings":"","what":"Method get_name()","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Get value name section. name Rd topic.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"usage-6","dir":"Reference","previous_headings":"","what":"Usage","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"","code":"RoxyTopic$get_name()"},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"returns-6","dir":"Reference","previous_headings":"","what":"Returns","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Character scalar.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"method-inherits-from-","dir":"Reference","previous_headings":"","what":"Method inherits_from()","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Query topics topic inherits type .","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"usage-7","dir":"Reference","previous_headings":"","what":"Usage","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"","code":"RoxyTopic$inherits_from(type)"},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"arguments-5","dir":"Reference","previous_headings":"","what":"Arguments","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"type Section type, character scalar.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"returns-7","dir":"Reference","previous_headings":"","what":"Returns","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"character vector topic names.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"method-inherits-section-from-","dir":"Reference","previous_headings":"","what":"Method inherits_section_from()","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Query topics topic inherits sections .","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"usage-8","dir":"Reference","previous_headings":"","what":"Usage","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"","code":"RoxyTopic$inherits_section_from()"},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"returns-8","dir":"Reference","previous_headings":"","what":"Returns","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"character vector topic names.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"method-add-","dir":"Reference","previous_headings":"","what":"Method add()","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Add one sections topic.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"usage-9","dir":"Reference","previous_headings":"","what":"Usage","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"","code":"RoxyTopic$add(x, block = \"???\", overwrite = FALSE)"},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"arguments-6","dir":"Reference","previous_headings":"","what":"Arguments","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"x Section(s) add. may another RoxyTopic object, sections added; rd_section object; list rd_section objects add. block Name block use error messages. overwrite Whether overwrite existing section. FALSE two sections merged.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"method-add-section-","dir":"Reference","previous_headings":"","what":"Method add_section()","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Add section.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"usage-10","dir":"Reference","previous_headings":"","what":"Usage","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"","code":"RoxyTopic$add_section(section, block = \"???\", overwrite = FALSE)"},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"arguments-7","dir":"Reference","previous_headings":"","what":"Arguments","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"section rd_section object add. block Name block use error messages. overwrite Whether overwrite existing section. FALSE two sections merged.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"Ensures type name (given name), appears self$sections. method internal use .","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"method-clone-","dir":"Reference","previous_headings":"","what":"Method clone()","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"objects class cloneable method.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"usage-11","dir":"Reference","previous_headings":"","what":"Usage","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"","code":"RoxyTopic$clone(deep = FALSE)"},{"path":"https://roxygen2.r-lib.org/dev/reference/RoxyTopic.html","id":"arguments-8","dir":"Reference","previous_headings":"","what":"Arguments","title":"A RoxyTopic is an ordered collection of unique rd_sections — RoxyTopic","text":"deep Whether make deep clone.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/double_escape_md.html","id":null,"dir":"Reference","previous_headings":"","what":"Check markdown escaping — double_escape_md","title":"Check markdown escaping — double_escape_md","text":"regression test Markdown escaping.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/double_escape_md.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Check markdown escaping — double_escape_md","text":"","code":"double_escape_md(text)"},{"path":"https://roxygen2.r-lib.org/dev/reference/double_escape_md.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Check markdown escaping — double_escape_md","text":"text Input text.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/double_escape_md.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Check markdown escaping — double_escape_md","text":"Double-escaped text.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/double_escape_md.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Check markdown escaping — double_escape_md","text":"following bullets look rendered: Backticks: \\, \\%, \\$, \\_ \\verb{}: \\, \\%, \\$, \\_ [ link ] \\[ neither \\]","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/double_escape_md.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Check markdown escaping — double_escape_md","text":"","code":"\"%\" # percent #> [1] \"%\" \"\\\"\" # double quote #> [1] \"\\\"\" '\\'' # single quote #> [1] \"'\""},{"path":"https://roxygen2.r-lib.org/dev/reference/escape_examples.html","id":null,"dir":"Reference","previous_headings":"","what":"Escape examples — escape_examples","title":"Escape examples — escape_examples","text":"documentation topic used primarily testing record understanding \\example{} escaping rules. See https://developer.r-project.org/parseRd.pdf details provided R core.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/escape_examples.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Escape examples — escape_examples","text":"","code":"escape_examples(x)"},{"path":"https://roxygen2.r-lib.org/dev/reference/escape_examples.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Escape examples — escape_examples","text":"","code":"# In examples we automatically escape Rd comments (%): 100 %% 30 #> [1] 10 # even if they are in strings \"50%\" #> [1] \"50%\" # and \\ and \\v inside of strings and symbols \"\\v\" # vertical tab #> [1] \"\\v\" \"\\\\\" #> [1] \"\\\\\" # but not comments: \\l \\v # other string escapes are left as is \"\\\"\" #> [1] \"\\\"\" \"\\n\" #> [1] \"\\n\" # Otherwise, backslashes and parentheses are left as is. This # means that you need to escape unbalanced parentheses, which typically only # occur in \\dontshow{}: if (FALSE) { print(\"Hello\") } # You also need to escape backslashes in infix operators and comments # (this is generally rare) `%\\\\%` <- function(x, y) x + y 10 %\\% 20 #> [1] 30 # \\\\ (renders as two backslashes)"},{"path":"https://roxygen2.r-lib.org/dev/reference/is_s3_generic.html","id":null,"dir":"Reference","previous_headings":"","what":"Determine if a function is an S3 generic or S3 method. — is_s3_generic","title":"Determine if a function is an S3 generic or S3 method. — is_s3_generic","text":"is_s3_generic compares name .knownS3Generics .S3PrimitiveGenerics, looks function body see calls UseMethod(). is_s3_method builds names possible generics function checks actually generic.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/is_s3_generic.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Determine if a function is an S3 generic or S3 method. — is_s3_generic","text":"","code":"is_s3_generic(name, env = parent.frame()) is_s3_method(name, env = parent.frame())"},{"path":"https://roxygen2.r-lib.org/dev/reference/is_s3_generic.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Determine if a function is an S3 generic or S3 method. — is_s3_generic","text":"name Name function. env Base environment look function definition.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/load.html","id":null,"dir":"Reference","previous_headings":"","what":"Load package code — load","title":"Load package code — load","text":"roxygen2 dynamic documentation system, means works objects inside package, just source code used create . functions offer various ways loading package suit various constraints: load_pkgload() uses pkgload::load_all() simulate package loading closely know . offers high fidelity handling code uses S4, requires package compiled. load_source() simulates package loading attaching packages listed Depends Imports, sources files R/ directory. default strategy used roxygen2 6.0.0 earlier; primary advantage need compilation. load_installed() uses installed version package. Use strategy installed development version package already. highest fidelity strategy, requires work outside roxygen2. can change default strategy function roxygen2 load option. Override default pkgload use source installed strategies:","code":"Roxygen: list(load = \"source\")"},{"path":"https://roxygen2.r-lib.org/dev/reference/load.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Load package code — load","text":"","code":"load_pkgload(path) load_installed(path) load_source(path)"},{"path":"https://roxygen2.r-lib.org/dev/reference/load.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Load package code — load","text":"path Path source package","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/load_options.html","id":null,"dir":"Reference","previous_headings":"","what":"Load roxygen2 options — load_options","title":"Load roxygen2 options — load_options","text":"Options can stored Roxygen field DESCRIPTION, man/roxygen/meta.R. either case, code parsed evaluated child base environment. Call roxy_meta_get() access current option values within tag roclet methods. Options man/roxygen/meta.R override present DESCRIPTION.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/load_options.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Load roxygen2 options — load_options","text":"","code":"load_options(base_path = \".\") roxy_meta_get(key = NULL, default = NULL)"},{"path":"https://roxygen2.r-lib.org/dev/reference/load_options.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Load roxygen2 options — load_options","text":"base_path Path package.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/load_options.html","id":"possible-options","dir":"Reference","previous_headings":"","what":"Possible options","title":"Load roxygen2 options — load_options","text":"roclets : giving names roclets run. See roclet_find() details. packages : packages load implement new tags. load : load R code. See load details. old_usage : use old style usage formatting? markdown : translate markdown syntax Rd? r6 : document R6 classes? current_package (read ): name package documented. rd_family_title : overrides @family titles. See rd vignette details: vignette(\"rd\", package = \"roxygen2\") knitr_chunk_options : default chunk options used knitr. restrict_image_formats : TRUE PDF images included PDF manual, SVG images included HTML manual. (applies images supplied via markdown.)","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/load_options.html","id":"how-to-set","dir":"Reference","previous_headings":"","what":"How to set","title":"Load roxygen2 options — load_options","text":"Either set DESCRIPTION: longer, can put /man/roxygen/meta.R:","code":"Roxygen: list(markdown = TRUE, load = \"installed\") list( markdown = TRUE, load = \"installed\" )"},{"path":"https://roxygen2.r-lib.org/dev/reference/markdown-internals.html","id":null,"dir":"Reference","previous_headings":"","what":"Escape Rd markup, to avoid interpreting it as markdown — escape_rd_for_md","title":"Escape Rd markup, to avoid interpreting it as markdown — escape_rd_for_md","text":"needed, want stay compatible existing markup, even markdown mode switched . Fragile Rd tags (tags may contain markup can picked markdown parser), replaced placeholders. markdown Rd conversion done, original text put back place placeholders. puts back protected fragile Rd commands text markdown parsing.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/markdown-internals.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Escape Rd markup, to avoid interpreting it as markdown — escape_rd_for_md","text":"","code":"escape_rd_for_md(text) unescape_rd_for_md(rd_text, esc_text)"},{"path":"https://roxygen2.r-lib.org/dev/reference/markdown-internals.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Escape Rd markup, to avoid interpreting it as markdown — escape_rd_for_md","text":"text Input text. Potentially contains Rd /markdown markup. rd_text markdown parsed interpreted text. esc_text original escaped text escape_rd_for_md().","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/markdown-internals.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Escape Rd markup, to avoid interpreting it as markdown — escape_rd_for_md","text":"escape_rd_for_md: “safe” version input text, fragile Rd tag replaced placeholder. original text added attribute placeholder. unescape_rd_for_md: Rd text.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/markdown-internals.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Escape Rd markup, to avoid interpreting it as markdown — escape_rd_for_md","text":"list protected Rd tags escaped_for_md. Rd macros treated specially: , markdown allowed second argument. ifelse markdown allowed second third arguments. See also roclet-rd.R list tags uses markdown-enabled parser. tags, e.g. @aliases, @backref, etc. use standard Roxygen parser.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/markdown-test.html","id":null,"dir":"Reference","previous_headings":"","what":"Dummy page to test roxygen's markdown formatting — markdown-test","title":"Dummy page to test roxygen's markdown formatting — markdown-test","text":"Links tricky, put links : Link function: roxygenize(). Link object: roxygenize (just treat like object .","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/markdown-test.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Dummy page to test roxygen's markdown formatting — markdown-test","text":"Link another package, function: desc::desc(). Link another package, non-function: desc::desc. Link link text: great function, roxygenize, great function. another package: one. table:","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/markdown_pass1.html","id":null,"dir":"Reference","previous_headings":"","what":"Expand the embedded inline code — markdown_pass1","title":"Expand the embedded inline code — markdown_pass1","text":"Expand embedded inline code","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/markdown_pass1.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Expand the embedded inline code — markdown_pass1","text":"","code":"markdown_pass1(text)"},{"path":"https://roxygen2.r-lib.org/dev/reference/markdown_pass1.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Expand the embedded inline code — markdown_pass1","text":"text Input text.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/markdown_pass1.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Expand the embedded inline code — markdown_pass1","text":"Text R code expanded. character vector length input text.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/markdown_pass1.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Expand the embedded inline code — markdown_pass1","text":"example becomes two: 2. Variables can set reused, within tag: value x 100. access internal functions package, e.g. since roxygen2, can refer internal markdown function, TRUE: TRUE. insert name current package: roxygen2. iris data set 5 columns: Sepal.Length, Sepal.Width, Petal.Length, Petal.Width, Species. Chunk options: Plots: Alternative knitr engines: Also see vignette(\"rd-formatting\").","code":"# Code block demo x + 1 #> [1] 101 names(mtcars) nrow(mtcars) #> [1] \"mpg\" \"cyl\" \"disp\" \"hp\" \"drat\" \"wt\" \"qsec\" \"vs\" \"am\" \"gear\" #> [11] \"carb\" #> [1] 32 plot(1:10) ```{r} # comment this <- 10 is <- this + 10 good <- this + is"},{"path":"https://roxygen2.r-lib.org/dev/reference/namespace_roclet.html","id":null,"dir":"Reference","previous_headings":"","what":"Roclet: make NAMESPACE — namespace_roclet","title":"Roclet: make NAMESPACE — namespace_roclet","text":"roclet automates production NAMESPACE file, controls functions imported exported package, described Writing R extensions. NAMESPACE generated two passes: first generates import directives (can computed without evaluating package code), second generates everything (package loaded). See vignette(\"namespace\") details.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/namespace_roclet.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Roclet: make NAMESPACE — namespace_roclet","text":"","code":"namespace_roclet()"},{"path":[]},{"path":"https://roxygen2.r-lib.org/dev/reference/namespace_roclet.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Roclet: make NAMESPACE — namespace_roclet","text":"","code":"# 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 #> NULL"},{"path":"https://roxygen2.r-lib.org/dev/reference/object.html","id":null,"dir":"Reference","previous_headings":"","what":"Constructors for S3 object to represent R objects. — object","title":"Constructors for S3 object to represent R objects. — object","text":"objects usually created parsers, also useful generate hand testing.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/object.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Constructors for S3 object to represent R objects. — object","text":"","code":"object(value, alias, type)"},{"path":"https://roxygen2.r-lib.org/dev/reference/object.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Constructors for S3 object to represent R objects. — object","text":"value object . alias Alias object documented, case create generator function different name.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/object_format.html","id":null,"dir":"Reference","previous_headings":"","what":"Default format for data — object_format","title":"Default format for data — object_format","text":"function called generate default \"Format\" section data object. default implementation return class dimension information.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/object_format.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Default format for data — object_format","text":"","code":"object_format(x)"},{"path":"https://roxygen2.r-lib.org/dev/reference/object_format.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Default format for data — object_format","text":"x data object","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/object_format.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Default format for data — object_format","text":"character value valid Rd syntax, NULL.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/parse_package.html","id":null,"dir":"Reference","previous_headings":"","what":"Parse a package, file, or inline code — parse_package","title":"Parse a package, file, or inline code — parse_package","text":"parse_package(), parse_file(), parse_text() allow use roxygen's parsing code parse roxygen blocks package, file, character vector code. env_package() env_file() provide defaults generate temporary environment making possible associate block corresponding live object.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/parse_package.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Parse a package, file, or inline code — parse_package","text":"","code":"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)"},{"path":"https://roxygen2.r-lib.org/dev/reference/parse_package.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Parse a package, file, or inline code — parse_package","text":"path, file, text Either specify path root directory package, R file, character vector text. env environment environment containing result evaluating input code. defaults test environment: real code need generate environment . can also set NULL want get tokenized code blocks . suppresses evaluation @eval tags, find code object associated block.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/parse_package.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Parse a package, file, or inline code — parse_package","text":"list roxy_block objects","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/rd_roclet.html","id":null,"dir":"Reference","previous_headings":"","what":"Roclet: make Rd files — rd_roclet","title":"Roclet: make Rd files — rd_roclet","text":"roclet workhorse roxygen2, producing .Rd files R uses document functions, datasets, packages, classes, . See vignette(\"rd\") details. Generally call function directly instead use roxygenise() specifying rd roclet.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/rd_roclet.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Roclet: make Rd files — rd_roclet","text":"","code":"rd_roclet()"},{"path":[]},{"path":"https://roxygen2.r-lib.org/dev/reference/rd_roclet.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Roclet: make Rd files — rd_roclet","text":"","code":"#' 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) { }"},{"path":"https://roxygen2.r-lib.org/dev/reference/rd_section.html","id":null,"dir":"Reference","previous_headings":"","what":"Construct an rd_section object — rd_section","title":"Construct an rd_section object — rd_section","text":"rd_section represents Rd command can appear top-level Rd document, like \\name{}, \\title{}, \\description{}, \\section{}.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/rd_section.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Construct an rd_section object — rd_section","text":"","code":"rd_section(type, value)"},{"path":"https://roxygen2.r-lib.org/dev/reference/rd_section.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Construct an rd_section object — rd_section","text":"type Section type. Stored type field, class rd_section_{type}. avoid namespace clashes different extensions, include package name. value Section data. used format() merge() methods.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/rd_section.html","id":"methods","dir":"Reference","previous_headings":"","what":"Methods","title":"Construct an rd_section object — rd_section","text":"provide rd_section type, also need define format.rd_section_{type} method returns formatted Rd output. may also need provide merge.rd_section_{type} method two sections can combined rd_section(x$type, c(x$value, y$value)). See vignette(\"extending\") details.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roc_proc_text.html","id":null,"dir":"Reference","previous_headings":"","what":"Process roclet on string and capture results. — roc_proc_text","title":"Process roclet on string and capture results. — roc_proc_text","text":"Useful testing.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roc_proc_text.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Process roclet on string and capture results. — roc_proc_text","text":"","code":"roc_proc_text(roclet, input, wd = NULL)"},{"path":"https://roxygen2.r-lib.org/dev/reference/roc_proc_text.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Process roclet on string and capture results. — roc_proc_text","text":"roclet Name roclet use processing. input Source string wd Working directory","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roclet.html","id":null,"dir":"Reference","previous_headings":"","what":"Build a new roclet. — roclet","title":"Build a new roclet. — roclet","text":"create new roclet, need create constructor function wraps roclet, implement methods described .","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roclet.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Build a new roclet. — roclet","text":"","code":"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)"},{"path":"https://roxygen2.r-lib.org/dev/reference/roclet.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Build a new roclet. — roclet","text":"x roclet object. blocks list roxy_block objects. base_path Path root source package. env Package environment. results Value returned roclet_process() method.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roclet.html","id":"methods","dir":"Reference","previous_headings":"","what":"Methods","title":"Build a new roclet. — roclet","text":"roclet_preprocess() called blocks parsed code evaluated. needed roclet affects code evaluated. return roclet. roclet_process() called blocks evaluated; .e. @eval tag processed, object associated block determined. roclet_output() given output roclet_process() produce files disk. roclet_clean() called roxygenise(clean = TRUE). remove files created roclet.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roclet.html","id":"deprecated-methods","dir":"Reference","previous_headings":"","what":"Deprecated methods","title":"Build a new roclet. — roclet","text":"roclet_tags() longer used; instead provide roxy_tag_parse() method tag.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roclet_find.html","id":null,"dir":"Reference","previous_headings":"","what":"Create a roclet from a string. — roclet_find","title":"Create a roclet from a string. — roclet_find","text":"provides flexible way specifying roclet string.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roclet_find.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create a roclet from a string. — roclet_find","text":"","code":"roclet_find(x)"},{"path":"https://roxygen2.r-lib.org/dev/reference/roclet_find.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create a roclet from a string. — roclet_find","text":"x Arbitrary R code evaluated roxygen2 package.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roclet_find.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create a roclet from a string. — roclet_find","text":"","code":"# rd, namespace, and vignette work for backward compatibility roclet_find(\"rd\") #> list() #> attr(,\"class\") #> [1] \"roclet_rd\" \"roclet\" # But generally you should specify the name of a function that # returns a roclet roclet_find(\"rd_roclet\") #> list() #> attr(,\"class\") #> [1] \"roclet_rd\" \"roclet\" # If it lives in another package, you'll need to use :: roclet_find(\"roxygen2::rd_roclet\") #> list() #> attr(,\"class\") #> [1] \"roclet_rd\" \"roclet\" # If it takes parameters (which no roclet does currently), you'll need # to call the function roclet_find(\"roxygen2::rd_roclet()\") #> list() #> attr(,\"class\") #> [1] \"roclet_rd\" \"roclet\""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxy_block.html","id":null,"dir":"Reference","previous_headings":"","what":"Blocks — roxy_block","title":"Blocks — roxy_block","text":"roxy_block represents single roxygen2 block. block_* functions provide helpers common operations: block_has_tag(blocks, tags): block contain tags? block_get_tags(block, tags): get instances tags block_get_tag(block, tag): get single tag. Returns NULL 0, throws warning 1. block_get_tag_value(block, tag): gets val field single tag.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxy_block.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Blocks — roxy_block","text":"","code":"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)"},{"path":"https://roxygen2.r-lib.org/dev/reference/roxy_block.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Blocks — roxy_block","text":"tags list roxy_tags. file, line Location call (.e. line last line block). call Expression associated block. object Optionally, object associated block, found inspecting/evaluating call. block roxy_block manipulate. tag single tag name.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxy_block.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Blocks — roxy_block","text":"","code":"# 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 #> [:6] #> $tag #> [line: 2] @title 'This is a title' {parsed} #> [line: 4] @param 'x,y A number' {parsed} #> [line: 5] @export '' {parsed} #> [line: 6] @usage '' {parsed} #> [line: 6] @.formals '' {parsed} #> [line: 6] @backref '' {parsed} #> $call f <- function(x, y) x + y #> $object #> $topic f #> $alias f"},{"path":"https://roxygen2.r-lib.org/dev/reference/roxy_tag.html","id":null,"dir":"Reference","previous_headings":"","what":"roxy_tag S3 constructor — roxy_tag","title":"roxy_tag S3 constructor — roxy_tag","text":"roxy_tag() constructor tag objects. roxy_tag_warning() superseded warn_roxy_tag(); use generate warning includes location tag.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxy_tag.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"roxy_tag S3 constructor — roxy_tag","text":"","code":"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())"},{"path":"https://roxygen2.r-lib.org/dev/reference/roxy_tag.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"roxy_tag S3 constructor — roxy_tag","text":"tag Tag name. Arguments starting . reserved internal usage. raw Raw tag value, string. val Parsed tag value, typically character vector, sometimes list. Usually filled tag_parsers file, line Location tag x tag","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxy_tag.html","id":"methods","dir":"Reference","previous_headings":"","what":"Methods","title":"roxy_tag S3 constructor — roxy_tag","text":"Define method roxy_tag_parse support new tags. See tag_parsers details.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxy_tag_rd.html","id":null,"dir":"Reference","previous_headings":"","what":"Generate Rd output from a tag — roxy_tag_rd","title":"Generate Rd output from a tag — roxy_tag_rd","text":"Provide method generic want tag generate output .Rd files. See vignette(\"extending\") details.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxy_tag_rd.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Generate Rd output from a tag — roxy_tag_rd","text":"","code":"roxy_tag_rd(x, base_path, env)"},{"path":"https://roxygen2.r-lib.org/dev/reference/roxy_tag_rd.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Generate Rd output from a tag — roxy_tag_rd","text":"x tag base_path Path package root directory. env Environment evaluate code (needed)","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxy_tag_rd.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Generate Rd output from a tag — roxy_tag_rd","text":"Methods must return rd_section.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxygen2-package.html","id":null,"dir":"Reference","previous_headings":"","what":"roxygen2: In-Line Documentation for R — roxygen2-package","title":"roxygen2: In-Line Documentation for R — roxygen2-package","text":"Generate Rd documentation, 'NAMESPACE' file, collation field using specially formatted comments. Writing documentation -line code makes easier keep documentation --date requirements change. 'roxygen2' inspired 'Doxygen' system C++.","code":""},{"path":[]},{"path":"https://roxygen2.r-lib.org/dev/reference/roxygen2-package.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"roxygen2: In-Line Documentation for R — roxygen2-package","text":"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] contributors: Posit Software, PBC [copyright holder, funder]","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxygenize.html","id":null,"dir":"Reference","previous_headings":"","what":"Process a package with the Rd, namespace and collate roclets — roxygenize","title":"Process a package with the Rd, namespace and collate roclets — roxygenize","text":"workhorse function uses roclets, built-document transformation functions, build documentation package. See documentation individual roclets, rd_roclet(), namespace_roclet(), update_collate(), details.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxygenize.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Process a package with the Rd, namespace and collate roclets — roxygenize","text":"","code":"roxygenize(package.dir = \".\", roclets = NULL, load_code = NULL, clean = FALSE) roxygenise(package.dir = \".\", roclets = NULL, load_code = NULL, clean = FALSE)"},{"path":"https://roxygen2.r-lib.org/dev/reference/roxygenize.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Process a package with the Rd, namespace and collate roclets — roxygenize","text":"package.dir Location package top level directory. Default working directory. roclets Character vector roclet names use package. default, NULL, uses roxygen roclets option, defaults c(\"collate\", \"namespace\", \"rd\"). load_code function used load R code package directory. default, NULL, uses strategy defined load roxygen option, defaults load_pkgload(). See load details. clean TRUE, roxygen delete files previously created roxygen running roclet.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxygenize.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Process a package with the Rd, namespace and collate roclets — roxygenize","text":"NULL","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/roxygenize.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Process a package with the Rd, namespace and collate roclets — roxygenize","text":"Note roxygen2 dynamic documentation system: works inspecting loaded objects package. means must able load package order document : see load details.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/tag_parsers.html","id":null,"dir":"Reference","previous_headings":"","what":"Parse tags — tag_parsers","title":"Parse tags — tag_parsers","text":"functions parse raw tag value, convert string richer R object storing val, provide informative warning returning NULL.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/tag_parsers.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Parse tags — tag_parsers","text":"","code":"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)"},{"path":"https://roxygen2.r-lib.org/dev/reference/tag_parsers.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Parse tags — tag_parsers","text":"x roxy_tag object parse first, second Name first second parts two part tags required second part required (TRUE) can blank (FALSE)? markdown second part parsed markdown? min, max Minimum maximum number words","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/tag_parsers.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Parse tags — tag_parsers","text":"roxy_tag object val field set parsed value.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/tag_parsers.html","id":"new-tag","dir":"Reference","previous_headings":"","what":"New tag","title":"Parse tags — tag_parsers","text":"create new @mytag define roxy_tag_parse.roxy_tag_mytag(). either call one functions , directly set x$val.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/tags-index-crossref.html","id":null,"dir":"Reference","previous_headings":"","what":"Tags for indexing and cross-references — tags-index-crossref","title":"Tags for indexing and cross-references — tags-index-crossref","text":"Learn full details vignette('index-crossref'). Key tags: @aliases ${1:alias}: Add additional aliases topic. Use NULL suppress default alias automatically generated roxygen2. @concept ${1:concept}: Add additional keywords phrases included help.search() index. @concept single term phrase. @family ${1:family name}: Generate @seealso entries functions family name. @keywords ${1:keyword}: Add standardised keyword, indexed help.search(). generally useful apart @keywords internal flags topic internal removes topic indexes. @references ${1:reference}: Pointers related literature. Usually formatted like bibliography. @seealso [${1:func}()]: Link related functions urls. Usually sentence two, bulleted list. less frequently used tags: @backref ${1:path}: Manually override backreference points .Rd file back source .R file. needed generating code.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/tags-index-crossref.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Tags for indexing and cross-references — tags-index-crossref","text":"","code":"#' @aliases ${1:alias} #' @backref ${1:path} #' @concept ${1:concept} #' @family ${1:family name} #' @keywords ${1:keyword} #' @references ${1:reference} #' @seealso [${1:func}()]"},{"path":[]},{"path":"https://roxygen2.r-lib.org/dev/reference/tags-namespace.html","id":null,"dir":"Reference","previous_headings":"","what":"Tags for managing the NAMESPACE — tags-namespace","title":"Tags for managing the NAMESPACE — tags-namespace","text":"Learn full details vignette('namespace'). Key tags: @export: Export function, method, generic, class available outside package. @exportS3Method ${1:package}::${2:generic}: Export S3 method. needed method generic suggested package. @importFrom ${1:package} ${2:function}: Import specific functions package. @useDynLib ${1:package}: Import compiled code another package. less frequently used tags: @evalNamespace ${1:r-code}: Evaluate arbitrary code package namespace insert results NAMESPACE. return character vector directives. @exportClass ${1:class}: Export S4 class. expert use ; cases use @export roxygen2 can automatically generate correct directive. @exportMethod ${1:generic}: Export S4 methods. expert use ; cases use @export roxygen2 can automatically generate correct directive. @exportPattern ${1:pattern}: Export objects matching regular expression. @import ${1:package}: Import functions package. Use extreme care. @importClassesFrom ${1:package} ${2:class}: Import S4 classes another package. @importMethodsFrom ${1:package} ${2:generic}: Import S4 methods package. @rawNamespace ${1:namespace directives}: Insert literal text directly NAMESPACE.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/tags-namespace.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Tags for managing the NAMESPACE — tags-namespace","text":"","code":"#' @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}"},{"path":"https://roxygen2.r-lib.org/dev/reference/tags-rd-formatting.html","id":null,"dir":"Reference","previous_headings":"","what":"Tags related to markdown support — tags-rd-formatting","title":"Tags related to markdown support — tags-rd-formatting","text":"Learn full details vignette('rd-formatting'). less frequently used tags: @md: Force markdown processing block. @noMd: Suppress markdown processing block. @section ${1:section title}: : Add arbitrary section documentation. Now generally superseded favour using level 1 heading.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/tags-rd-formatting.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Tags related to markdown support — tags-rd-formatting","text":"","code":"#' @md #' @noMd #' @section ${1:section title}:"},{"path":"https://roxygen2.r-lib.org/dev/reference/tags-rd-other.html","id":null,"dir":"Reference","previous_headings":"","what":"Tags for documenting datasets and classes — tags-rd-other","title":"Tags for documenting datasets and classes — tags-rd-other","text":"Learn full details vignette('rd-'). Key tags: @field ${1:name} ${2:description}: Describe R6 refClass field. @format ${1:description}: Describe type/shape dataset. dataset data frame, include description column. supplied, automatically generated object_format(). @method ${1:generic} ${2:class}: Force function recognised S3 method. affects default usage NAMESPACE directive produced @export. needed automatic detection fails. @slot ${1:name} ${2:description}: Describe slot S4 class. @source ${1:description}: Describe dataset came . Provide link original source (possible) briefly describe manipulation performed importing data.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/tags-rd-other.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Tags for documenting datasets and classes — tags-rd-other","text":"","code":"#' @field ${1:name} ${2:description} #' @format ${1:description} #' @method ${1:generic} ${2:class} #' @slot ${1:name} ${2:description} #' @source ${1:description}"},{"path":[]},{"path":"https://roxygen2.r-lib.org/dev/reference/tags-rd.html","id":null,"dir":"Reference","previous_headings":"","what":"Tags for documenting functions — tags-rd","title":"Tags for documenting functions — tags-rd","text":"Learn full details vignette('rd'). Key tags: @description${1:short description...} : short description purpose function. Usually around paragraph, can longer needed. @example ${1:path}.R: Embed examples stored another file. @examples${1:# example code} : Executable R code demonstrates function works. Code must run without error. @examplesIf ${1:condition}${2:# example code} : Run examples condition TRUE. @noRd: Suppress .Rd generation block. Use documentation blocks visible source code. @param ${1:name} ${2:description}: Describe function input. describe acceptable input types affects output. description usually one two sentences can long needed. Document multiple arguments separating names commas without spaces. @returns ${1:description}: Describe function's output. Typically 1-2 sentence description output type, might also include discussion important errors warnings. @title ${1:title}: one-line description function shown various indexes. explicit @title usually needed default taken first paragraph roxygen block. @usage ${1:fun}(${2:arg1, arg2 = default, ...}): Override default usage generated roxygen2. needed roxygen2 fails correctly derive usage function. less frequently used tags: @details${1:Additional details...} : Additional details function. Generally superseded instead using level 1 heading. @rawRd ${1:rd}: Insert literal text directly .Rd file. @return ${1:description}: Describe function's output. Superseded favour @returns.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/tags-rd.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Tags for documenting functions — tags-rd","text":"","code":"#' @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, ...})"},{"path":[]},{"path":"https://roxygen2.r-lib.org/dev/reference/tags-reuse.html","id":null,"dir":"Reference","previous_headings":"","what":"Tags that help you reuse documentation — tags-reuse","title":"Tags that help you reuse documentation — tags-reuse","text":"Learn full details vignette('reuse'). Key tags: @describeIn ${1:destination} ${2:description}: Document function method destination topic. @inherit ${1:source} ${2:components}: Inherit one documentation components another topic. components omitted, supported components inherited. Otherwise, specify individual components inherit picking one params, return, title, description, details, seealso, sections, references, examples, author, source, note, format. @inheritDotParams ${1:source} ${2:arg1 arg2 arg3}: Automatically generate documentation ... passing dots along another function. @inheritParams ${1:source}: Inherit argument documentation another function. inherits documentation arguments already documented locally. @inheritSection ${1:source} ${2:section name}: Inherit specific named section another topic. @order ${1:number}: Override default (lexigraphic) order multiple blocks combined single topic. @rdname ${1:topic-name}: Override file name generated .Rd file. Can used combine multiple blocks single documentation topic. less frequently used tags: @eval ${1:r-code}: Evaluate arbitrary code package namespace insert results back block. return character vector lines. @evalRd ${1:r-code}: Evaluate arbitrary code package namespace insert results back block. return character vector lines. @includeRmd man/rmd/${1:filename}.Rmd: Insert contents .Rmd current block. Superseded favour using code chunk child document. @template ${1:path--template}: Use roxygen2 template. Now superseded favour inline R code. @templateVar ${1:name} ${2:value}: Define variables use roxygen2 template.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/tags-reuse.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Tags that help you reuse documentation — tags-reuse","text":"","code":"#' @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}"},{"path":[]},{"path":"https://roxygen2.r-lib.org/dev/reference/tags_list.html","id":null,"dir":"Reference","previous_headings":"","what":"Access metadata about built-in tags — tags_list","title":"Access metadata about built-in tags — tags_list","text":"Access metadata built-tags","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/tags_list.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Access metadata about built-in tags — tags_list","text":"","code":"tags_list(built_in = TRUE) tags_metadata()"},{"path":"https://roxygen2.r-lib.org/dev/reference/update_collate.html","id":null,"dir":"Reference","previous_headings":"","what":"Update Collate field in DESCRIPTION — update_collate","title":"Update Collate field in DESCRIPTION — update_collate","text":"default, R loads files alphabetical order. Unfortunately every alphabet puts letters order, rely alphabetic ordering need one file loaded another. (usually matter important S4, need make sure classes loaded subclasses generics defined methods.). can override default alphabetical ordering @include .R, specify .R must loaded current file. Generally, need run function ; run automatically package needs load R files collation order.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/update_collate.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Update Collate field in DESCRIPTION — update_collate","text":"","code":"update_collate(base_path)"},{"path":"https://roxygen2.r-lib.org/dev/reference/update_collate.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Update Collate field in DESCRIPTION — update_collate","text":"base_path Path package directory.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/update_collate.html","id":"collate","dir":"Reference","previous_headings":"","what":"Collate","title":"Update Collate field in DESCRIPTION — update_collate","text":"roclet roclets need values objects package, values can generated unless sourced files, source files unless know correct order. @include tags, roxygen2 leave collate . makes easier use roxygen2 existing collate directive, remove @include tags, need also manually delete collate field.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/update_collate.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Update Collate field in DESCRIPTION — update_collate","text":"","code":"#' 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 #> NULL"},{"path":"https://roxygen2.r-lib.org/dev/reference/vignette_roclet.html","id":null,"dir":"Reference","previous_headings":"","what":"Re-build outdated vignettes — vignette_roclet","title":"Re-build outdated vignettes — vignette_roclet","text":"roclet rebuilds outdated vignettes tools::buildVignette, longer recommend longer recommend storing built vignettes package. default, rebuild vignettes source file newer output pdf html. (means automatically re-build vignette change vignette source, change R code). want finer control, add Makefile vignettes/ roxygen2 use instead. prevent RStudio re-building vignettes checking package, add ---build-vignettes \"Build Source Package\" field project options.","code":""},{"path":"https://roxygen2.r-lib.org/dev/reference/vignette_roclet.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Re-build outdated vignettes — vignette_roclet","text":"","code":"vignette_roclet()"},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-development-version","dir":"Changelog","previous_headings":"","what":"roxygen2 (development version)","title":"roxygen2 (development version)","text":"S3 method export warning longer fails class contains { } (#1575). @family lists now ordered carefully, “foo1” comes “foo” (#1563, @krlmlr). @importFrom works quoted non-syntactic names, e.g. @importFrom magrittr \"%>%\" @importFrom rlang `:=` (#1570, @MichaelChirico). unquoted form @importFrom magrittr %>% continues work. Relatedly, @importFrom directives matching known functions (e.g. @importFrom utils plot pdf) produce valid NAMESPACE files . Multi-line @rawNamespace longer break re-runs namespace_roclet() (#1572, @MichaelChirico).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-730","dir":"Changelog","previous_headings":"","what":"roxygen2 7.3.0","title":"roxygen2 7.3.0","text":"CRAN release: 2024-01-11","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"new-features-7-3-0","dir":"Changelog","previous_headings":"","what":"New features","title":"roxygen2 7.3.0","text":"@docType package now works like documenting \"_PACKAGE\", creating {packagename}-package alias clearly suggesting switch \"_PACKAGE\" instead (#1491). _PACKAGE longer generate alias package name function name exists (#1160). NAMESPACE roclet now reports S3 methods missing @export tag. S3 methods need @exported (confusingly really registers method) even generic . avoids rare, hard debug, problems (#1175). can suppress warning @exportS3Method NULL (#1550). NAMESPACE roclet regenerates imports loading package code parsing roxygen blocks. goal long time (#372), accidentally broke adding support code execution markdown blocks. resolves family problems somehow bork NAMESPACE can’t easily get can’t re-document package code doesn’t reload.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"minor-improvements-and-bug-fixes-7-3-0","dir":"Changelog","previous_headings":"","what":"Minor improvements and bug fixes","title":"roxygen2 7.3.0","text":"document function another package automatically imported. Additionally, set @rdname @name can opt default reexports topic generation provide docs (#1408). Generate correct usage S4 methods non-syntactic class names. ROXYGEN_PKG env var provides name package documented (#1517). @describeIn foo now suggests might want @rdname instead (#1493). also gives informative warning use unsupported type (#1490). DESCRIPTION, URLs containing escapes URL BugReports now correctly handled (@HenningLorenzen-ext-bayer, #1415). Authors can now multiple email addresses (@jmbarbone, #1487). escape_examples() now exported (#1450). @exportS3Method provides needed metadata generate correct usage S3 methods, just like @method (#1202). is_s3_generic() now ignores non-function objects looking candidate function. believe closer R operates. @import friends now ignored try import package documented. useful add self-dependencies standalone files meant used packages (r-lib/usethis#1853). @importFrom throws friendlier error try import non-existing functions (@MichaelChirico, #1409). @include now gives informative warning use path doesn’t exist (#1497). @inherit can now also inherit @format (#1293).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-723","dir":"Changelog","previous_headings":"","what":"roxygen2 7.2.3","title":"roxygen2 7.2.3","text":"CRAN release: 2022-12-08 roxygen2 now supports HTML blocks markdown. included HTML manual. can also produced output code chunks. Improved support RStudio IDE.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-722","dir":"Changelog","previous_headings":"","what":"roxygen2 7.2.2","title":"roxygen2 7.2.2","text":"CRAN release: 2022-11-11 @includeRmd calls local_reproducible_output() make code run included .Rmds consistent sources (#1431). Fix duplicated argument roxy_block() avoid CRAN removal.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-721","dir":"Changelog","previous_headings":"","what":"roxygen2 7.2.1","title":"roxygen2 7.2.1","text":"CRAN release: 2022-07-18","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"tags-7-2-1","dir":"Changelog","previous_headings":"","what":"Tags","title":"roxygen2 7.2.1","text":"built-tags now documented can (e.g.) ?\"@param\" get basic description @param pointer learn (#1165). powered new tags_list() lists tags defined roxygen2 tags_metadata() provides useful information use (e.g.) IDEs (#1375). @describeIn can now used combine types functions (generics, methods functions) single topic. resulting section organises functions type (#1181) displays methods like function calls. Methods recognized extend generic destination,destination can heuristically identified constructor. Code evaluated inline markdown code chunks @eval/@evalRd/ @evalNamespace now evaluated environment designed reproducible suppress output won’t work Rd (e.g. turning colour unicode support cli) (#1351). now also set knitr options comment = #> (#1380) collapse = TRUE (#1376). @export now export class constructor function applied expressions like foo <- setClass(\"foo\") (#1216). @includeRmd now gives better feedback fails (#1089).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"rmarkdown-7-2-1","dir":"Changelog","previous_headings":"","what":"(R)markdown","title":"roxygen2 7.2.1","text":"New knitr_chunk_options option (Roxygen entry DESCRIPTION man/roxygen/meta.R) added knitr chunk options roxygen2 uses markdown code blocks inline code (#1390). PDF figures included PDF manual, SVG figures included HTML manual (#1399). can now use alternative knitr engines markdown code blocks (#1149). Generated HTML code blocks never includes “NA” language (#1251). Using level 1 heading wrong tag now gives useful warning (#1374). Fix bug interpolating results indented inline RMarkdown (#1353).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"other-7-2-1","dir":"Changelog","previous_headings":"","what":"Other","title":"roxygen2 7.2.1","text":"daily build RStudio, lists changed Rd files now clickable can immediately see rendered development documentation (#1354). R6 documentation longer shows inherited methods aren’t (#1371), links superclass docs ’re actually available (#1236). Automated usage longer mangles nbsp default arguments (#1342).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-720","dir":"Changelog","previous_headings":"","what":"roxygen2 7.2.0","title":"roxygen2 7.2.0","text":"CRAN release: 2022-05-13","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"new-features-7-2-0","dir":"Changelog","previous_headings":"","what":"New features","title":"roxygen2 7.2.0","text":"NAMESPACE roclet now preserves existing non-import directives ’s first pre-processing pass. eliminates “NAMESPACE changed” messages reduces incidence namespace borking (#1254). @inheritParams now inherits exact multiparameter matches, ’re inheriting function @param x,y ’ll get parameter documentation function needs docs x y (#950). warning messages reviewed informative actionable (#1317). @title now checks multiple paragraphs. @export gives informative warning contains many lines. (#1074). tags warn now provide whitespace (#1228), problems first tag block reported correct line number (#1235). daily build RStudio, roxygen2 warnings now include clickable hyperlink take directly problem (#1323). technology active development across IDE cli package extremely exciting.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"minor-improvements-and-bug-fixes-7-2-0","dir":"Changelog","previous_headings":"","what":"Minor improvements and bug fixes","title":"roxygen2 7.2.0","text":"roxygen2 can read UTF-8 paths windows (#1277). @authors de-duplicated merged documentation (@DanChaltiel, #1333). @exportS3method pkg::generic now works pkg::generic isn’t imported package (#1085). @includeRmd now adapted change rmarkdown 2.12 regarding math support github_document() (#1304). @inherit friends perform less aggressive link tweaking, eliminating many spurious warnings. Additionally, get warning, ’ll now always learn topic ’s coming (#1135). Inherited \\ifelse{}{}{} tags now inserted correctly (without additional {}) (#1062). @inherit now supports inheriting “Notes” @inherit pkg::fun note (@pat-s, #1218) Automatic @usage now correctly wraps arguments containing syntactically significant whitespace (e.g anonymous functions) (#1281) non-syntactic values surrounded backticks (#1257). Markdown: Code blocks always wrapped
even language unknown (#1234). Links markup (e.g. [foo `bar`][target]) now cause informative warning instead generating invalid Rd. Curly braces links now escaped (#1259). Inline R code now powered knitr. available, (knit) print methods applied (#1179). change alters outputs brings roxygen line console R markdown behavior. x <- \"foo\" longer inserts anything resulting documentation, x <- \"foo\"; x . also means returning character vector insert commas components, newlines. roxygen2 longer generates invalid HTML (#1290). DOIs, arXiv links, urls Description field DESCRIPTION now converted appropriate Rd markup (@dieghernan, #1265, #1164). DOIs URL field DESCRIPTION now converted Rd’s special \\doi{} tag (@ThierryO, #1296).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-712","dir":"Changelog","previous_headings":"","what":"roxygen2 7.1.2","title":"roxygen2 7.1.2","text":"CRAN release: 2021-09-08 new @examplesIf tag can used create conditional examples. examples run specified condition holds (#962). roxygen2 now licensed MIT (#1163). Bug fix upcoming stringr 2.0.0 release. Code blocks language now add sourceCode generated div; makes syntax highlighting consistent across downlit/pandoc/knitr/roxygen2. Percent signs markdown link targets, e.g. [text](https://foo/ba%20r) now handled correctly (#1209).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-711","dir":"Changelog","previous_headings":"","what":"roxygen2 7.1.1","title":"roxygen2 7.1.1","text":"CRAN release: 2020-06-27 processing cross package markdown links (e.g. [pkg::fun()]), roxygen2 now looks file needs link , instead linking topic, avoid “Non-file package-anchored links” R CMD check warnings. R6 methods re-exported functions always sorted C locale; ensures ’re always sorted way every environment (#1077). roxygen2 now supports inline markdown code code chunks inside Rd tags. particular \\{} (#1115).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-710","dir":"Changelog","previous_headings":"","what":"roxygen2 7.1.0","title":"roxygen2 7.1.0","text":"CRAN release: 2020-03-11","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"new-features-7-1-0","dir":"Changelog","previous_headings":"","what":"New features","title":"roxygen2 7.1.0","text":"roxygen2 now supports inline markdown code also code chunks, using notation knitr package. example: See vignette(\"rd-formatting\") details. roxygen2 now keeps using Windows (CR LF) line endings files already CR LF line endings, uses LF new files (#989).","code":"#' 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) #' ```"},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"minor-improvements-and-bug-fixes-7-1-0","dir":"Changelog","previous_headings":"","what":"Minor improvements and bug fixes","title":"roxygen2 7.1.0","text":"Auto-generated package documentation can now handle author ORCID comments containing full url (#1040). Hyperlinks R6 methods also added PDF manual (#1006). Empty annotations (alternate text) figures added via markdown now omitted. caused issues generating pkgdown web sites (#1051). Roxygen metadata can now packages element, giving character vector package names load. makes easier use extension package provide new tags existing roclets (#1013). See ?load_options details. @evalNamespace() works (#1022). @description NULL @details NULL longer fail; instead, tags ignored, except @description NULL package level documentation, can used suppress auto-generated Description section (#1008). Multiple @format tags now combined (#1015). warning @section titles spanning multiple lines now includes hint ’re missing colon (@maelle, #994). Can now document objects created delayedAssign() forcing evaluation documentation time (#1041)","code":"Roxygen: list(markdown = TRUE, packages = \"roxygenlabs\")"},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-702","dir":"Changelog","previous_headings":"","what":"roxygen2 7.0.2","title":"roxygen2 7.0.2","text":"CRAN release: 2019-12-02 \\example{} escaping improved (!) special escapes within strings correctly escaped (#990).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-701","dir":"Changelog","previous_headings":"","what":"roxygen2 7.0.1","title":"roxygen2 7.0.1","text":"CRAN release: 2019-11-22 @includeRmd now optional second argument, top level section included file go . defaults details section (#970). Code chunks now evaluated child global environment (#972). @inheritParams better job munging links. Links form \\link[=topic]{text} now automatically converted \\link[pkg:topic]{text} inherited packages (#979). Internal has_topic() helper better implementation; means links longer munged unnecessarily (#973). \\example{} escaping considerably simplified (#967), now documented escape_example(). \\usage{}, S3/S4 methods longer double-escaped (#976). Markdown tables cells contain multiple elements (e.g. text code) now rendered correctly (#985). Markdown code blocks containing operators special syntax (e.g. function, , +) now converted \\code{} \\verb{} (#971).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-700","dir":"Changelog","previous_headings":"","what":"roxygen2 7.0.0","title":"roxygen2 7.0.0","text":"CRAN release: 2019-11-12","code":""},{"path":[]},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"new-tags-7-0-0","dir":"Changelog","previous_headings":"New features","what":"New tags","title":"roxygen2 7.0.0","text":"@includeRmd {path.Rmd} converts .Rmd/.md file .Rd includes manual page. allows sharing text vignettes, README.Rmd, documentation. See vignette(\"rd\") details (#902). @order {n} tag controls order blocks processed. can use override usual ordering proceeds top file bottom. @order 1 processed @order 2, blocks don’t explicit order set (#863). @exportS3Method tag allows generate S3method() namespace directives (note different capitalisation) (#796). primary use “delayed” method registration, allows define methods generics found suggested packages (available R 3.6 greater). example, generate (See vctrs::s3_register() need version works earlier versions R). also two argument form allows generate arbitrary S3method() directives: New @returns alias @return (#952).","code":"#' @exportS3Method package::generic generic.foo <- function(x, ...) { } S3method(package::generic, foo) #' @exportS3Method generic class NULL S3method(generic, class)"},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"r6-7-0-0","dir":"Changelog","previous_headings":"New features","what":"R6","title":"roxygen2 7.0.0","text":"roxygen2 can now document R6 classes (#922). See vignette(\"rd\") details.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"markdown-improvements-7-0-0","dir":"Changelog","previous_headings":"New features","what":"Markdown improvements","title":"roxygen2 7.0.0","text":"Rd comments (%) now automatically escaped. need replace existing uses \\% % (#879). Markdown headings supported tags like @description, @details, @return (#907, #908). Level 1 headings create new top-level \\section{}. Level 2 headings create nested \\subsections{}. Markdown tables converted \\tabular{} macro (#290). roxygen2 supports GFM table syntax looks like : Markdown code (`foofy`) converted either \\code{} \\verb{}, depending whether parses R code. better matches description \\code{} \\verb{} macros, solves certain class escaping problems, make easier include arbitrary “code” snippets documentation without causing Rd failures (#654). Markdown links can now contain formatting, e.g. [*mean*][mean] now generate \\link[=mean]{\\emph{mean}}. Use unsupported markdown features (e.g. blockquotes, inline HTML, horizontal rules) generates informative error messages (#804).","code":"| foo | bar | | --- | --- | | baz | bim |"},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"default-usage-7-0-0","dir":"Changelog","previous_headings":"New features","what":"Default usage","title":"roxygen2 7.0.0","text":"default formatting function usage spans multiple lines now changed. Previously, usage wrapped produce smallest number lines, e.g.: Now wrapped argument gets line (#820): prefer old behaviour can put following DESCRIPTION:","code":"parse_package(path = \".\", env = env_package(path), registry = default_tags(), global_options = list()) parse_package( path = \".\", env = env_package(path), registry = default_tags(), global_options = list() ) Roxygen: list(old_usage = TRUE)"},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"code-loading-7-0-0","dir":"Changelog","previous_headings":"New features","what":"Code loading","title":"roxygen2 7.0.0","text":"roxygen2 now provides three strategies loading code (#822): load_pkgload(), default, uses pkgload. Compared previous release, now automatically recompiles package needed. load_source() attaches required packages source()s files R/. cruder simulation package loading pkgload (e.g. unreliable use S4 extensively), require package compiled. Use default strategy (used roxygen2 6.1.0 ) causes grief. load_installed() assumes installed package. best used part bigger automated workflow. can override default either calling (e.g.) roxygenise(load_code = \"source\")) setting load option DESCRIPTION: Roxygen: list(load = \"source\").","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"options-7-0-0","dir":"Changelog","previous_headings":"New features","what":"Options","title":"roxygen2 7.0.0","text":"well storing roxygen options Roxygen field DESCRIPTION can now also store man/roxygen/meta.R (#889). evaluation file produce named list maps option names values. roxygen now also looks templates man/roxygen/templates (#888). New rd_family_title option: named list, used overrides default “family:” prefix @family generates. example, override prefix generated @family foo place rd_family_title <- list(foo = \"Custom prefix: \") man/roxygen/meta.R (#830, @kevinushey).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"breaking-changes-7-0-0","dir":"Changelog","previous_headings":"","what":"Breaking changes","title":"roxygen2 7.0.0","text":"Rd comments (%) automatically escaped markdown formatted text. backward incompatible change need replace existing uses \\% % (#879). Using @docType package longer automatically adds -name. Instead document _PACKAGE get defaults package documentation, use @name override default file name. @S3method removed. deprecated roxygen2 4.0.0 released 2014-05-02, 5 years ago. Using old wrap option now trigger warning, hasn’t worked quite time. Suppress error deleting option DESCRIPTION.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"extending-roxygen2-7-0-0","dir":"Changelog","previous_headings":"Breaking changes","what":"Extending roxygen2","title":"roxygen2 7.0.0","text":"process extending roxygen2 new tags new roclets completely overhauled, now documented vignette(\"extending\"). ’re one people written roxygen2 extension, break code - documentation, object structure, print methods now much better hope ’s annoying! interface now documented, change future without warning deprecation cycle. previously made new roclet, major changes : previously internal data structures used represent blocks tags overhauled. now documented stable. See roxy_block() roxy_tag() details. roclet_tags() longer used; instead define roxy_tag_parse() method. example, create new @mytag tag, generate class roxy_tag_mytag, parsed roxy_tag_parse.roxy_tag_mytag() method. method return new roxy_tag() object val field set. means registry argument longer needed removed. rd_section() roxy_tag_rd() now exported can easily extend rd_roclet() tags generate output .Rd files. global_options longer passed roclet methods. Instead, use roxy_meta_get() retrieve values stored options (#918). tag_two_part() tag_words() now simple functions, function factories. tag_markdown_restricted() removed exactly thing tag_markdown(). big thanks goes @mikldk starting vignette motivating make extension process much pleasant (#882).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"bug-fixes-and-minor-improvements-7-0-0","dir":"Changelog","previous_headings":"","what":"Bug fixes and minor improvements","title":"roxygen2 7.0.0","text":"Empty roxygen2 lines start block now silently removed (#710). Whitespace automatically trimmed RoxygenNote field comparing installed version roxygen2 version used generate documentation (#802). Files generated Windows systems now retain existing line endings, use unix-style line endings new files (@jonthegeek, @jimhester, #840). roxygen2 now recognises fully qualified S4 functions like methods::setGeneric(), methods::setClass() methods::setMethod() (#880). Package documentation now converts ORCIDs useful link (#721). package logo (found man/images/logo.png) now scaled 120px wide (@peterdesmet, #834). Documenting S4 method .local() wrapper longer fails obscure error message (#847). Functions documented reexports now sorted alphabetically package (#765). @describeIn can now used combination function types (#666, #848). @description @detail tags automatically generated leading description block, now correct line numbers (#917). @example @examples interwoven order appear (#868). @examples, escaped ' \" strings longer doubly escaped (#873). @family automatically adds () linking functions (#815), print link line (improve diffs). @inheriting external documentation, \\link{foo} links automatically transformed \\link{package}{foo} work generated documentation (#635). \\href{} links external inherited now inserted correctly (without additional {}) (#778). @inheriting function arguments longer throws confusing error message (#898). @inheritDotParams automatically ignores arguments can’t inherited ... used current function (@mjskay, #885). @inheritDotParams includes link function wraps parameters \\code{} (@halldc, #842). @inheritDotParams can repeated inherit dot docs multiple functions (@gustavdelius, #767). @inheritDotParams avoids multiple ... arguments (@gustavdelius, #857). @inheritParams ignores leading dots comparing argument names (#862). @inheritParams warns parameters require documentation (#836). @param containing whitespace gives clear warning message (#869). Multiple @usage statements single block now generate warning. Previously, first used without warning.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-611","dir":"Changelog","previous_headings":"","what":"roxygen2 6.1.1","title":"roxygen2 6.1.1","text":"CRAN release: 2018-11-07 Now specifically imports recent version desc package (>= 1.2.0) fix various parsing issues (@crsh, #773, #777, #779). Multi-line DESCRIPTION collate directives now correctly parsed windows (@brodieG, #790). roxygenise() longer recompiles packages containing src code (#784). roxygenise() now stops informative error message run directory ’s package root (@mikmart, #704).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-610","dir":"Changelog","previous_headings":"","what":"roxygen2 6.1.0","title":"roxygen2 6.1.0","text":"CRAN release: 2018-07-27","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"new-features-6-1-0","dir":"Changelog","previous_headings":"","what":"New features","title":"roxygen2 6.1.0","text":"NAMESPACE roclet now works two passes - first generates NAMESPACE containing import directives can generated without evaluating code package. alleviates problem previously possible get state get carefully editing NAMESPACE hand (#372). @evalRd foo() evaluates foo() defined package namespace inserts results current block (#645). code return character vector one entry line (start #'). two small limitations current implementation: generated roxygen affect @md/@noMd status @evalRd work inside templates. @evalNamespace NAMESPACE @evalRd Rd files: give R code produces literal entry NAMESPACE run. make easier export functions generated functions package (#531, @egnha). @inherits can now inherit examples (#588). vignette(\"rd\") received thorough updating current best-practices. vignette still needs work pull requests greatly appreciated (#650). roxygenise() uses pkgload::load_all() instead home grown solution simulate package loading (needed roxygen2 uses run-time information generate documentation). reduce S4 related problems ensures devtools::document() roxygenise() always exactly behaviour (#568, #595). inherited section found, warning contains help page section requested (#732, @krlmlr). roxygen2 now always reads writes using UTF-8 encoding. used package Encoding: UTF-8 DESCRIPTION, ’ll now get warning (#564, #592).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"extension-api-6-1-0","dir":"Changelog","previous_headings":"","what":"Extension API","title":"roxygen2 6.1.0","text":"Roxygen blocks now official structure encoded roxy_block(). named list containing tags attributes providing metadata. parsed argument roclet_process() replaced separate blocks env arguments. New roclet_preprocess() generic makes possible roclets perform actions code evaluated. parse_package(), parse_file() parse_code() provide exported API allows use roxygen’s parsing code independently creating roclets.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"minor-improvements-and-bug-fixes-6-1-0","dir":"Changelog","previous_headings":"","what":"Minor improvements and bug fixes","title":"roxygen2 6.1.0","text":"tags (including @alias) now de-duplicated consistently sorted. reduces spurious diffs (#586, @flying-sheep). @concept now generates one \\concept per tag (#611). default @description (.e. title) now added much later process. means @inherit description now works specified title inheritor (#629) default description slightly nicer merging multiple blocks. @family automatically adds value concepts (#611). @inherits: mechanism extracting inherited Rd better job preserving escapes (#624) Empty .Rbuildignore now handled correctly (#576). Stricter regular expression ensures files ending .R .r parsed roxygen comments (#625). Objects names starting dot now default documented files prefix ‘dot-’. Roclets can now access global options designed. allows templates use markdown formatting set globally (#594). can now autogenerate package documentation even don’t Authors@R (#606). Multiple given /family names now supported Authors@R field DESCRIPTION file (#672, @sgibb). package logo exists (man/figures/logo.png) automatically included generated package docs (#609). Usage data objects now correctly generated, avoiding double escaping components usage (#562). Improvements markdown translation: Code link text now properly rendered code (#620, @egnha). Whitespace words link text now preserved single space links form [text][fcn] [text](URL) (#628, #754, #760, @egnha @jennybc). % inline code (#640), code blocks (@nteetor, #699) links (#724) now automatically escaped. Parsing markdown links tweaked reduce false positives (#555). still get false positive, can now put \\\\ front [ avoid converted link (#720). Links can longer followed { avoid spurious matches Rd commands like \\Sexpr{}. Unsupported markdown features now generate mildly helpful warning instead throwing utterly useless error (#560). person() now supports MARC Relator role codes (#662, @publicus). topic_add_usage() now outputs formatted “Usage” section max width 80 characters thanks now flexible wrap_string() (@JoshOBrien, #719).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-601","dir":"Changelog","previous_headings":"","what":"roxygen2 6.0.1","title":"roxygen2 6.0.1","text":"CRAN release: 2017-02-06 Allowing empty lines .Rbuildignore. Previously, empty lines caused files ignored. (#572, @jakob-r) Automatically generating usage section infix function containing “<-” longer removes “<-” function name (#554).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-600","dir":"Changelog","previous_headings":"","what":"roxygen2 6.0.0","title":"roxygen2 6.0.0","text":"CRAN release: 2017-01-31","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"markdown-6-0-0","dir":"Changelog","previous_headings":"","what":"Markdown","title":"roxygen2 6.0.0","text":"fields can now written using Markdown markup instead traditional Rd language. can turn Markdown globally adding Roxygen: list(markdown = TRUE) DESCRIPTION. @md / @noMd tags turn Markdown parsing / given block. See vignette(\"markdown\") details (#364, #431, #499, #506, #507), @gaborcsardi","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"improved-inheritance-6-0-0","dir":"Changelog","previous_headings":"","what":"Improved inheritance","title":"roxygen2 6.0.0","text":"New @inheritDotParams allows automatically generate parameter documentation ... common case pass ... another function (#512). often override arguments, comes flexible specification argument selection: @inheritDotParams foo takes parameters foo() @inheritDotParams foo b e:h takes parameters , b, parameters e h @inheritDotParams foo -x -y takes parameters except x y. documentation generated similar style used ?plot eventually incorporated RStudio’s autocomplete. New @inherit generalises @inheritParams, allows inherit parameters, return, references, title, description, details, sections, seealso. default @inherit my_fun inherit , can document object entirely specifying @inherit tag. Alternatively, can select specific tags inherit @inherit my_fun return params (#384). New @inheritSection fun title allows inherit contents single section another topic (#513). @inheritParams now works recursively, can inherit parameters function inherited parameters somewhere else. also better handles \\dots alias ... (#504).","code":""},{"path":[]},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"tags-6-0-0","dir":"Changelog","previous_headings":"Minor improvements and bug fixes","what":"Tags","title":"roxygen2 6.0.0","text":"@aliases longer sorted alphabetically, instead match order usage. gives control pkgdown. @describeIn now escapes special characters function names (#450). @family see alsos added order appear, alphabetically (#315). Fixed issue .s sometimes added words within @family tag (#477, @kevinushey). @author rendered @seealso. @example gives nice warning message accidentally use instead @examples (#494). Multiple @examples sections merged (#472, @krlmlr). Roxygen longer write topics don’t name title, instead generate warning. makes easier detect ’ve accidentally used @rdname incorrect value (#474).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"s3-6-0-0","dir":"Changelog","previous_headings":"Minor improvements and bug fixes","what":"S3","title":"roxygen2 6.0.0","text":"Non-primitive, internal S3 generics (e.g. ‘rbind’, ‘cbind’) now properly detected S3 generics. (#488, @kevinushey) Ensure functions S3 class still treated functions (#455). S3 method declarations via R.methodS3::setMethodS3() function declarations via R.oo::setConstructorS3() now supported (@HenrikBengtsson, #525).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"s4-6-0-0","dir":"Changelog","previous_headings":"Minor improvements and bug fixes","what":"S4","title":"roxygen2 6.0.0","text":"can now document setClassUnion()s (#514). default alias S4 method now re-adds trailing signatures sometimes dropped (#460). Back references now wrapped multiple lines, long (#493, @LiNk-NY).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"other-6-0-0","dir":"Changelog","previous_headings":"Minor improvements and bug fixes","what":"Other","title":"roxygen2 6.0.0","text":"\"_PACKAGE\" documentation now generates default @seealso combining URL BugReport fields, default @author field generated Authors@R field (#527). now works roxygenise(); worked devtools::document() (#439, @krlmlr). Manually created NAMESPACE documentation files never overwritten, even using roxygen2 first time (@krlmlr, #436). Changes DESCRIPTION (.e. Collate: RoxygenNote) now use desc package. minimise spurious changes (#430). default_data_format() renamed object_format(). New roclet_find() provides flexible way specify roclets: roclet name (e.g. “rd_roclet”), package (“foo::roclet_bar”), options (“foo::roclet_bar(baz = TRUE)”). usage replacement functions uses non-breaking spaces <- never get put line (#484). Roxygen now parses nonASCII documentation correctly (long UTF-8 encoded specified Encoding DESCRIPTION) (#532, @shrektan), ignores files listed .Rbuildignore (#446, @fmichonneau).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"extending-roxygen2-6-0-0","dir":"Changelog","previous_headings":"","what":"Extending roxygen2","title":"roxygen2 6.0.0","text":"Deprecated register.preref.parser() register.preref.parsers() removed. register_tags() also removed favour new roclet_tags() generic. roclet() (constructor), roclet_tags(), roclet_process() roclet_output(), roc_clean() now exported making possible create roclets packages. Helper functions roxy_tag() roxy_tag_warning() also exported. new_roclet() longer exported - use roclet() instead.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-501","dir":"Changelog","previous_headings":"","what":"roxygen2 5.0.1","title":"roxygen2 5.0.1","text":"CRAN release: 2015-11-11 Use ls(), names() list elements environment: fixes R 3.1.0 incompatibility (#422, @kevinushey). @export allows trailing new line (#415). Fixed bug @noRd, usage cause error (#418).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-500","dir":"Changelog","previous_headings":"","what":"roxygen2 5.0.0","title":"roxygen2 5.0.0","text":"CRAN release: 2015-10-28","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"new-features-5-0-0","dir":"Changelog","previous_headings":"","what":"New features","title":"roxygen2 5.0.0","text":"Roxygen now records version single place: RoxygenNote field DESCRIPTION (#338). last time roxygen2 upgrade changes every file man/. can now easily re-export functions ’ve imported another package: imported--re-exported functions documented file (rexports.Rd), containing brief description links original documentation (#376). can easily generate package documentation documenting special string “_PACKAGE” (@krlmlr, #349): title description automatically filled DESCRIPTION. New tags @rawRd @rawNamespace allow insert raw (unescaped) Rd NAMESPACE (useful conditional imports). @evalRd() similar, instead literal Rd, give R code produces literal Rd code run. make easier experiment new types output (#385). roxygen2 now parses source code files order specified Collate field DESCRIPTION. improves ordering generated documentation using @describeIn /@rdname split across several .R files, often happens working S4 (#323, #324).","code":"#' @export magrittr::`%>%` #' @details Details \"_PACKAGE\""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"minor-features-and-bug-fixes-5-0-0","dir":"Changelog","previous_headings":"","what":"Minor features and bug fixes","title":"roxygen2 5.0.0","text":"contents documented functions now also parsed roxygen comments. allows, e.g., documenting parameter’s type close type checked, documenting implementation details close source, simplifies future extensions documentation R6 classes (#397, @krlmlr). Data objects get simpler default @format describes object’s class dimensions. former default, generated generated str(), didn’t usually produce useful output quite slow. new S3 generic default_data_format() generates format can overridden generate custom format (#410, @krlmlr). roxygen parsers completely rewritten C++ (#295). gives nice performance boost gives: Better error messages: now get exact line number tag, just start block. parser simplified little: tags now must always start new line. recommended practice anyway, means escaping inline @ (@@) now optional. (#235) Unknown tags now emit warning, rather error. @examples longer complains non-matching braces inside strings (#329). @family now cross-links manual page , instead linking aliases (@gaborcsardi, #283, #367). special @include parser also rewritten C++, giving performance boost larger packages (#401). particularly important ’s also called devtools::load_all(). Additionally, space @include longer necessary (@krlmlr, #342). @inheritParams foo::bar ensures % remains escaped (#313). document multiple arguments one @param, (e.g. @param ,b,c) parameter get space can wrapped generated Rd file (#373). @sections identical titles now merged together, just like @description @details. useful conjunction @rdname tag. (@krlmlr, #300). Automatic @usage now correctly generated functions string arguments containing \"\\\"\" (#265). load_options() now exported devtools::document() doesn’t run update_collate() twice (#395). update_collate() rewrites Collate entry DESCRIPTION file changes (#325, #723). empty NAMESPACE file written maintained roxygen2 (@krlmlr, #348). Data lazy-loaded can documented (@krlmlr, #390).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"internal-changes-5-0-0","dir":"Changelog","previous_headings":"","what":"Internal changes","title":"roxygen2 5.0.0","text":"register.preref.parser() register.preref.parsers() deprecated - please use register_tags() instead. Parser callbacks registered register_tags() now called fields parsed “introduction” (text first tag) (@gaborcsardi, #370).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-411","dir":"Changelog","previous_headings":"","what":"roxygen2 4.1.1","title":"roxygen2 4.1.1","text":"CRAN release: 2015-04-15 Formatting Authors@R field DESCRIPTION file now retained (@jranke, #330). collate roclet falls back base::strwrap() generating collate field. makes roxygen2 compatible next version stringr. New “vignette” roclet. vignette automatically rebuilds date vignettes (#314). --one error C++ Roxygen preparser fixed. new @backref tag makes possible override sourceref R code generators like Rcpp (@krlmlr, #291, #294).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-410","dir":"Changelog","previous_headings":"","what":"roxygen2 4.1.0","title":"roxygen2 4.1.0","text":"CRAN release: 2014-12-13 source documentation added autogenerated .Rd files. @include tags, roxygen2 leaves collate field alone. makes easier convert existing project uses predefined collate, start @include later remove , ’ll need also remove collate field (#302, #303). Protected dir() sort_c() - ’d noticed inconsistency ordering devtools::document() devtools::check() cause . Fixed broken regular expression caused problems stringr 1.0.0. Authors@R field DESCRIPTION now longer wrapped(@krlmlr, #284). @describeIn plain functions now correctly includes function name can applied data documentation. (@jimhester, #285, #288). Works called Rscript methods loaded (@krlmlr, #305).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-402","dir":"Changelog","previous_headings":"","what":"roxygen2 4.0.2","title":"roxygen2 4.0.2","text":"CRAN release: 2014-09-02 don’t use @exports namespace directives, namespace file touched (#276). Methods longer automatically attempt inherit parameters generic. ’s fraught difficulty (#261). Roxygen now understands setReplaceMethod() (#266). Parameter documentation ordered according order formals, possible (@krlmlr, #63). Export is_s3_method(). Roxygen longer fails run non-UTF-8 locales windows.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-401","dir":"Changelog","previous_headings":"","what":"roxygen2 4.0.1","title":"roxygen2 4.0.1","text":"CRAN release: 2014-05-17 Explicit updateRoxygen() longer needed - roxygenize() right thing first time run. Exporting S4 generic works (#246). roxygenise() longer complains absence wrap field ’s unlikely anyone wants old behaviour (#245).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-400","dir":"Changelog","previous_headings":"","what":"roxygen2 4.0.0","title":"roxygen2 4.0.0","text":"CRAN release: 2014-05-02 roxygen2 4.0.0 major update roxygen2 makes provides enhanced error handling considerably safer default behaviour. Now, roxygen2 never overwrite file create. means run first time, ’ll need run roxygen2::upgradeRoxygen(). flag existing files created roxygen2.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"new-features-4-0-0","dir":"Changelog","previous_headings":"","what":"New features","title":"roxygen2 4.0.0","text":"Six vignettes provide comprehensive overview using roxygen2 practice. Run browseVignettes(\"roxygen2\") access. @describeIn makes easier describe multiple functions one file. especially useful want document methods generic, common class, ’s also useful want document multiple related functions one file (#185). @field documents fields reference class (#181). works way @slot S4 classes. can now document objects defined elsewhere (like datasets) documenting name string (#221). example, document dataset called mydata, can : roxygen2 now adds comment generated files know ’ve generated, hand edited. roxygen2 longer wraps text Rd files default, .e. default option wrap = FALSE now. override , specify field Roxygen: list(wrap = TRUE) DESCRIPTION (#178). Roxygenise automatically deletes --date Rd files man/.","code":"#' Mydata set #' #' Some data I collected about myself \"mydata\""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"improved-error-handling-4-0-0","dir":"Changelog","previous_headings":"","what":"Improved error handling","title":"roxygen2 4.0.0","text":"roxygen2 never overwrite file generated roxygen2. means first time use version roxygen, ’ll need delete existing Rd files. roxygenise() gains clean argument automatically remove files previously created roxygen2. Parsing stricter: many issues previously warnings now errors. errors now give line number roxygen block associated error. Every input now checked make sure matching braces (e.g. every { matching }). prevent frustrating errors require careful reading .Rd files (#183). @section titles @export tags can now span single line prevent common bugs. @S3method deprecated - just use @export (#198). Namespace tags now throw parsing errors give bad inputs (#220). Better error message try document something NULL, assignment, class, generic method (#194).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"bug-fixes-and-minor-improvements-4-0-0","dir":"Changelog","previous_headings":"","what":"Bug fixes and minor improvements","title":"roxygen2 4.0.0","text":"Better parsing non-syntactic function names packages used @inheritParams (#236). Deprecated arguments roxygenise() (roxygen.dir, copy.package, overwrite, unlink.target) removed. Remove unneeded codetools tools dependencies. Bump required Rcpp version 0.11.0, remove custom makefiles. Non-syntactic argument names (like _x) now surrounded back-ticks usage (#191). internal parsers longer part public roxygen2 interface. Usage statements generated roxygen statements non-longer contain non-ASCII characters wrapped long (#180). default, reference classes now document methods, methods parents (#201). Default aliases always include original name object, even overridden @name. also means <- setClass(\"\") get two aliases default: -class (#202). Use @aliases NULL suppress default alias. Non-syntactic class names (like <-) now escaped usage section S4 methods (#205). Eliminated two cases wrapping occurred even wrap = FALSE.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-310","dir":"Changelog","previous_headings":"","what":"roxygen2 3.1.0","title":"roxygen2 3.1.0","text":"CRAN release: 2014-01-29","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"documentation-for-reference-classes-3-1-0","dir":"Changelog","previous_headings":"","what":"Documentation for reference classes","title":"roxygen2 3.1.0","text":"’s now possible document reference classes, using “docstring” convention described ?setRefClass. want provide short paragraph description method , make first component message string containing description, e.g.: Unlike documentation R functions, documentation methods can quite succinct. Roxygen adopts convention documented methods public, listed man page object. Undocumented methods private shown documentation. methods superclasses also listed, don’t need flip multiple pages documentation understand can object. documented methods placed bulleted list section titled “Methods”, method usage automatically prepended docstring.","code":"setRefClass(\"A\", methods = list( f = function(a, b) { \"Take numbers \\code{a} and \\code{b} and add them together\" a + b } ))"},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"minor-fixes-and-improvements-3-1-0","dir":"Changelog","previous_headings":"","what":"Minor fixes and improvements","title":"roxygen2 3.1.0","text":"Fixes Rcpp 0.11.0 compatibility. roxygenise() now invisible returns list files generated individual roclets. useful tools want figure extra files man/ directory. is_s3_generic() now recognises group generics (#166). Don’t try add parameters data objects (#165). Sort output families using C locale (#171). @family now escapes function names references (#172).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-300","dir":"Changelog","previous_headings":"","what":"roxygen2 3.0.0","title":"roxygen2 3.0.0","text":"CRAN release: 2013-12-06 roxygen2 now fully supports S4 RC (reference classes) - longer need manually add @alias @usage tags S4 classes, methods generics, RC classes. default usage definitions much better, generating correct usage data sets (#122), S3 methods (without additional @method tag), S4 generics, S4 methods, replacement (#119) infix functions. Backslashes function arguments correctly escaped. Usage statements also use sophisticated line wrapping algorithm cause fewer problems R CMD check line limit. (#89, #125). S4 classes, S4 methods, RC classes given better default topics, file names corresponding topics shorter. S4 methods automatically inherit parameter documentation generic. @slot name description allows document slots S4 class. S3 support also improved: roxygen2 now figures whether function S3 method generic. (rare cases incorrectly, use @method manually describe generic class associated method). means can remove existing uses @method, can replace @S3method @export. Roxygen now support package specific options Roxygen field DESCRIPTION. value field R code results list. Currently wrap roclet values supported: Turn Rd re-wrapping adding Roxygen: list(wrap = FALSE) Change default roclets specifying Roxygen: list(roclets = c(\"collate\", \"rd\")) Roxygen 3.0 also includes number minor fixes improvements: Infix functions now escaped correctly NAMESPACE. (Thanks @crowding, #111) roxygenise() now works like devtools::document() ever works current directory. arguments roxygen.dir, overwrite, copy.package unlink.target deprecated due potential data loss problems. collate roclet longer roclet: processes R files using custom code (statically, dynamically) designed executed code sourced. Run update_collate() update Collate directive based @include tags - none present, collate directive generated. @useDynLib now works possible specifications - include comma tag value, output passed . means @useDynLib mypackage, .registration = TRUE now generate useDynLib(mypackage, .registration = TRUE) NAMESPACE. (#124) inst directory created default (#56). Explicitly depend utils methods packages make roxygen compatible Rscript (#72). Import digest package instead depending . Always use C locale sorting NAMESPACE file tags .Rd files. ensures consistent ordering across systems (#127). Templates extension .r supported case-sensitive file systems (#115). Template variables now actually work (#160, thanks @bronaugh). Suppress default aliases, format usage @aliases NULL, @format NULL @usage NULL.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-222","dir":"Changelog","previous_headings":"","what":"roxygen2 2.2.2","title":"roxygen2 2.2.2","text":"CRAN release: 2011-12-01 Correctly use keyword datasets dataset (Fixes #60) Reference classes longer given incorrect docType (data).","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-221","dir":"Changelog","previous_headings":"","what":"roxygen2 2.2.1","title":"roxygen2 2.2.1","text":"CRAN release: 2011-11-19 Use unicode escapes test files tests pass platforms. Work around bug gsub C locale manually specifying Encoding().","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-22","dir":"Changelog","previous_headings":"","what":"roxygen2 2.2","title":"roxygen2 2.2","text":"CRAN release: 2011-11-12","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"new-features-2-2","dir":"Changelog","previous_headings":"","what":"New features","title":"roxygen2 2.2","text":"Package docType automatically add package alias, needed. (Fixes #4) Data docType automatically add datasets keyword, default usage, default format. (Fixes #5). Data docType automatically added data objects. New @encoding tag manually setting non-ASCII encodings needed. (Fixes #7)","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"bug-fixes-2-2","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"roxygen2 2.2","text":"write.description() now tries much harder respect users’ original DESCRIPTION field formatting instead forcibly re-wrapping certain fields 60 characters. @details @description now work correctly @useDynLib now works correctly: produces NAMESPACE file, instead separate (wrong) useDynLib statements . namespace import directives now behave way export directives, producing multiple single directives instead one multiple directive: @importClassesFrom pkg b now produces importClassesFrom(pkg, ) importClassesFrom(pkg, b) example files included @example can now use infix operators (e.g. %*%) things %, preceded backslash Rd file. behaviour already place examples directly included @examples. Aliases longer quoted, % escaped backslash (Fixes #24). Names also % escaped (Fixes #50) Replacement functions (e.g. foo<-) now get correct usage statements: foo() <- value instead foo()<-value. (Fixes #38) Functions arguments now correctly get usage statements (Fixes #35) Indentation examples now preserved (Fixes #27) roxygen2 replace characters valid filenames character substitute, e.g. [] becomes sub, <- becomes set (Fixes #6) Usage strings use non-breaking spaces prevent string default values containing whitespace split across multiple lines. may cause problems unlikely event default value containing non-breaking space (`“”’) (Fixes #21) Functions quoted names now get correct usage statements (Fixes #41) Objects longer exist documented (Fixes #42) Errors now display file name line number roxygen block help find problem. Thanks code contributions Renaud Gaujoux. (Fixes #13) Documentation untagged text @title, @description @details tags now produces correct output.","code":"@useDynLib packageName routine1 routine2 useDynLib(packageName, routine1) useDynLib(packageName, routine2)"},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-21","dir":"Changelog","previous_headings":"","what":"roxygen2 2.1","title":"roxygen2 2.1","text":"CRAN release: 2011-07-29","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"new-features-2-1","dir":"Changelog","previous_headings":"","what":"New features","title":"roxygen2 2.1","text":"package dependencies loaded automatically added support @source tag","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"bug-fixes-2-1","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"roxygen2 2.1","text":"NAMESPACE file longer needs exist Collate field DESCRIPTION longer needs exist = now recognised way assigning functions x$y <- function() {...} longer causes error @example longer added extra new-lines. Correct directory normalisation windows fixes broken test. special thanks goes Yihui Xie contributed fixes improvements (bar one) version!","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"roxygen2-20","dir":"Changelog","previous_headings":"","what":"roxygen2 2.0","title":"roxygen2 2.0","text":"CRAN release: 2011-07-23","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"major-changes-2-0","dir":"Changelog","previous_headings":"","what":"Major changes","title":"roxygen2 2.0","text":"now works run-time details give accurate output. requires source code roxygen documenting loaded prior documentation. roxygen attempt , need ensure required packages loaded. Run-time data fixes long standing bugs roxygen couldn’t correctly figure function usage. aware cases still need use @usage tag. written idiomatic R, uses S3 instead homegrown class system. roclets build internal data structure instead writing disk directly. means can now use @rdname tag merge documentation multiple functions one file, unique namespace directives written NAMESPACE (makes @importFrom much useful). features removed, may may (based feedback) reincluded. include callgraph roclet, R CMD roxygen, worked systems. templating system: use @template tag insert brew template stored man-roxygen. Template variables can set using @templateVar name value retrieved within template <%= name %> extensive use caching make repeated runs fast possible. clear caches guarantee complete rebuild, use clear_caches(). parsing “introduction” (text first tag) changed. Now title consists first paragraph (.e. text first empty line), second paragraph description others put details. component can overridden @title, @description @details appropriate.","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"minor-changes-2-0","dir":"Changelog","previous_headings":"","what":"Minor changes","title":"roxygen2 2.0","text":"@name always output alias, even @aliases used. @export correctly uses @method generate S3method namespace directive","code":""},{"path":"https://roxygen2.r-lib.org/dev/news/index.html","id":"new-tags-2-0","dir":"Changelog","previous_headings":"","what":"New tags","title":"roxygen2 2.0","text":"@rdname filename sets output filename (without extension). Use functions non-alphanumeric functions (e.g. [<-) want document multiple functions one file @template templatename includes documentation template (see ) @section Section title: contents includes section title. Don’t forget colon! separates title section contents. @description @details tags allow specify description details components template @family family name automatically adds see-also cross-references functions family. function can belong multiple families. @inheritParams name allows inherit documentation parameters another function, either within current package (function) installed package (package:function). Currently supports single inheritance (.e. can’t inherit function inherits another function), can multiple @inheritParams tags. @format implemented; existed roxygen package actually ignored","code":""}]