diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..3ac34c82 --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,126 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at codeofconduct@posit.co. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][https://github.com/mozilla/inclusion]. + +For answers to common questions about this code of conduct, see the FAQ at +. Translations are available at . + +[homepage]: https://www.contributor-covenant.org diff --git a/.github/SUPPORT.md b/.github/SUPPORT.md index e8744a17..21ac6299 100644 --- a/.github/SUPPORT.md +++ b/.github/SUPPORT.md @@ -57,7 +57,7 @@ Armed with your reprex, the next step is to figure out [where to ask](https://ww problem _is_ a bug or a feature request, you can easily return here and report it. -Before opening a new issue, be sure to [search issues and pull requests](https://github.com/tidyverse/roxygen2/issues) to make sure the +Before opening a new issue, be sure to [search issues and pull requests](https://github.com/r-lib/roxygen2/issues) to make sure the bug hasn't been reported and/or already fixed in the development version. By default, the search will be pre-populated with `is:issue is:open`. You can [edit the qualifiers](https://help.github.com/articles/searching-issues-and-pull-requests/) diff --git a/.github/workflows/R-CMD-check.yaml b/.github/workflows/R-CMD-check.yaml index b0d1b5e2..ee65ccb5 100644 --- a/.github/workflows/R-CMD-check.yaml +++ b/.github/workflows/R-CMD-check.yaml @@ -22,30 +22,29 @@ jobs: fail-fast: false matrix: config: - - {os: macOS-latest, r: 'release'} + - {os: macos-latest, r: 'release'} - {os: windows-latest, r: 'release'} # Use 3.6 to trigger usage of RTools35 - {os: windows-latest, r: '3.6'} + # use 4.1 to check with rtools40's older compiler + - {os: windows-latest, r: '4.1'} - # Use older ubuntu to maximise backward compatibility - - {os: ubuntu-18.04, r: 'devel', http-user-agent: 'release'} - - {os: ubuntu-18.04, r: 'release'} - - {os: ubuntu-18.04, r: 'oldrel-1'} - - {os: ubuntu-18.04, r: 'oldrel-2'} - - {os: ubuntu-18.04, r: 'oldrel-3'} - - {os: ubuntu-18.04, r: 'oldrel-4'} + - {os: ubuntu-latest, r: 'devel', http-user-agent: 'release'} + - {os: ubuntu-latest, r: 'release'} + - {os: ubuntu-latest, r: 'oldrel-1'} + - {os: ubuntu-latest, r: 'oldrel-2'} + - {os: ubuntu-latest, r: 'oldrel-3'} + - {os: ubuntu-latest, r: 'oldrel-4'} env: GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} R_KEEP_PKG_SOURCE: yes steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - uses: r-lib/actions/setup-pandoc@v2 - with: - pandoc-version: 2.17.1 - uses: r-lib/actions/setup-r@v2 with: diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index 0b260216..087f0b05 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -20,7 +20,7 @@ jobs: env: GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - uses: r-lib/actions/setup-pandoc@v2 @@ -39,7 +39,7 @@ jobs: - name: Deploy to GitHub pages 🚀 if: github.event_name != 'pull_request' - uses: JamesIves/github-pages-deploy-action@4.1.4 + uses: JamesIves/github-pages-deploy-action@v4.4.1 with: clean: false branch: gh-pages diff --git a/.github/workflows/pr-commands.yaml b/.github/workflows/pr-commands.yaml index 97271eb2..71f335b3 100644 --- a/.github/workflows/pr-commands.yaml +++ b/.github/workflows/pr-commands.yaml @@ -14,7 +14,7 @@ jobs: env: GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - uses: r-lib/actions/pr-fetch@v2 with: @@ -51,7 +51,7 @@ jobs: env: GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - uses: r-lib/actions/pr-fetch@v2 with: diff --git a/.github/workflows/test-coverage.yaml b/.github/workflows/test-coverage.yaml index 4b654182..2c5bb502 100644 --- a/.github/workflows/test-coverage.yaml +++ b/.github/workflows/test-coverage.yaml @@ -15,7 +15,7 @@ jobs: GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - uses: r-lib/actions/setup-r@v2 with: @@ -27,5 +27,24 @@ jobs: needs: coverage - name: Test coverage - run: covr::codecov(quiet = FALSE) + run: | + covr::codecov( + quiet = FALSE, + clean = FALSE, + install_path = file.path(Sys.getenv("RUNNER_TEMP"), "package") + ) shell: Rscript {0} + + - name: Show testthat output + if: always() + run: | + ## -------------------------------------------------------------------- + find ${{ runner.temp }}/package -name 'testthat.Rout*' -exec cat '{}' \; || true + shell: bash + + - name: Upload test results + if: failure() + uses: actions/upload-artifact@v3 + with: + name: coverage-test-failures + path: ${{ runner.temp }}/package diff --git a/DESCRIPTION b/DESCRIPTION index cc19faac..3359611a 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,13 +1,13 @@ Package: roxygen2 Title: In-Line Documentation for R -Version: 7.2.1.9000 +Version: 7.2.3.9000 Authors@R: c( - person("Hadley", "Wickham", , "hadley@rstudio.com", role = c("aut", "cre", "cph"), + person("Hadley", "Wickham", , "hadley@posit.co", role = c("aut", "cre", "cph"), comment = c(ORCID = "0000-0003-4757-117X")), person("Peter", "Danenberg", , "pcd@roxygen.org", role = c("aut", "cph")), person("Gábor", "Csárdi", , "csardi.gabor@gmail.com", role = "aut"), person("Manuel", "Eugster", role = c("aut", "cph")), - person("RStudio", role = c("cph", "fnd")) + person("Posit Software, PBC", role = c("cph", "fnd")) ) Description: Generate your Rd documentation, 'NAMESPACE' file, and collation field using specially formatted comments. Writing @@ -24,13 +24,12 @@ Imports: cli (>= 3.3.0), commonmark, desc (>= 1.2.0), - digest, knitr, methods, pkgload (>= 1.0.2), - purrr (>= 0.3.3), + purrr (>= 1.0.0), R6 (>= 2.1.2), - rlang (>= 1.0.0), + rlang (>= 1.0.6), stringi, stringr (>= 1.0.0), utils, @@ -40,7 +39,7 @@ Suggests: covr, R.methodsS3, R.oo, - rmarkdown, + rmarkdown (>= 2.16), testthat (>= 3.1.2), yaml LinkingTo: @@ -52,5 +51,5 @@ Config/testthat/edition: 3 Encoding: UTF-8 Language: en-GB Roxygen: list(markdown = TRUE, load = "installed") -RoxygenNote: 7.2.0.9000 +RoxygenNote: 7.2.2.9000 SystemRequirements: C++11 diff --git a/NEWS.md b/NEWS.md index 2619caf6..ee5ab8e1 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,20 @@ # roxygen2 (development version) +# roxygen2 7.2.3 + +* roxygen2 now supports HTML blocks in markdown. They are only included + in the HTML manual. They can also be produced as the output of code + chunks. + +* Improved support for RStudio IDE. + +# roxygen2 7.2.2 + +* `@includeRmd` calls `local_reproducible_output()` to make code run in + included `.Rmd`s more consistent with other sources (#1431). + +* Fix duplicated argument in `roxy_block()` to avoid CRAN removal. + # roxygen2 7.2.1 ## Tags diff --git a/R/block.R b/R/block.R index 0f82f007..438f939d 100644 --- a/R/block.R +++ b/R/block.R @@ -17,7 +17,7 @@ #' @param object Optionally, the object associated with the block, found #' by inspecting/evaluating `call`. #' @param block A `roxy_block` to manipulate. -#' @param tag,tags Either a single tag name, or a character vector of tag names. +#' @param tag A single tag name. #' @export #' @keywords internal #' @examples diff --git a/R/markdown.R b/R/markdown.R index 7e208dcb..4c5183c1 100644 --- a/R/markdown.R +++ b/R/markdown.R @@ -491,20 +491,17 @@ mdxml_heading <- function(xml, state) { } mdxml_html_block <- function(xml, state) { - if (state$tag$tag != "includeRmd") { - return(mdxml_unsupported(xml, state$tag, "HTML blocks")) - } + txt <- xml_text(xml) + txt <- gsub("}", "\\}", txt, fixed = TRUE) + txt <- gsub("{", "\\{", txt, fixed = TRUE) paste0( "\\if{html}{\\out{\n", - gsub("}", "\\}", xml_text(xml), fixed = TRUE), + txt, "}}\n" ) } mdxml_html_inline <- function(xml, state) { - if (state$tag$tag != "includeRmd") { - return(mdxml_unsupported(xml, state$tag, "inline HTML components")) - } paste0( "\\if{html}{\\out{", gsub("}", "\\}", xml_text(xml), fixed = TRUE), diff --git a/R/namespace.R b/R/namespace.R index 41a87a5e..89d66ffb 100644 --- a/R/namespace.R +++ b/R/namespace.R @@ -326,7 +326,7 @@ namespace_exports <- function(path) { return(character()) } - parsed <- parse(path, keep.source = TRUE) + parsed <- as.list(parse(path, keep.source = TRUE)) is_import <- function(x) is_call(x, c("import", "importFrom", "importClassesFrom", "importMethodsFrom", "useDynLib")) export_lines <- attr(parsed, "srcref")[!map_lgl(parsed, is_import)] unlist(lapply(export_lines, as.character)) diff --git a/R/object-from-call.R b/R/object-from-call.R index e7d965df..235b7d32 100644 --- a/R/object-from-call.R +++ b/R/object-from-call.R @@ -6,7 +6,7 @@ object_from_call <- function(call, env, block, file) { parser_data(call, env, file) } } else if (is.call(call)) { - call <- call_standardise(call, env) + call <- call_match(call, eval(call[[1]], env)) name <- deparse(call[[1]]) switch(name, "=" = , diff --git a/R/rd-include-rmd.R b/R/rd-include-rmd.R index d86675fa..04f0c970 100644 --- a/R/rd-include-rmd.R +++ b/R/rd-include-rmd.R @@ -10,7 +10,7 @@ roxy_tag_parse.roxy_tag_includeRmd <- function(x) { #' @export roxy_tag_rd.roxy_tag_includeRmd <- function(x, base_path, env) { - rmd <- x$val$path + rmd <- rel_rmd <- x$val$path section <- x$val$section if (!file.exists(rmd)) { @@ -49,6 +49,7 @@ roxy_tag_rd.roxy_tag_includeRmd <- function(x, base_path, env) { ) cat(txt, file = rmd_path) + local_reproducible_output() tryCatch( rmarkdown::render( rmd_path, @@ -62,7 +63,7 @@ roxy_tag_rd.roxy_tag_includeRmd <- function(x, base_path, env) { envir = new_environment(parent = global_env()) ), error = function(e) { - warn_roxy_tag(x, "failed to evaluate Rmd", parent = e) + warn_roxy_tag(x, "failed to evaluate {.path {rel_rmd}}", parent = e) } ) @@ -70,7 +71,13 @@ roxy_tag_rd.roxy_tag_includeRmd <- function(x, base_path, env) { return(NULL) } - value <- rmd_eval_rd(md_path, x) + tryCatch( + value <- rmd_eval_rd(md_path, x), + error = function(e) { + warn_roxy_tag(x, "failed to process result of {.path {rel_rmd}}", parent = e) + } + ) + rd_section_markdown(section, value) } diff --git a/R/rd-usage.R b/R/rd-usage.R index 72dfa604..f64d84d2 100644 --- a/R/rd-usage.R +++ b/R/rd-usage.R @@ -126,7 +126,7 @@ usage_args <- function(args) { text } - map_chr(args, arg_to_text) + map_chr(as.list(args), arg_to_text) } args_string <- function(x, space = " ") { diff --git a/R/select-args.R b/R/select-args.R index 2509506c..9f201c88 100644 --- a/R/select-args.R +++ b/R/select-args.R @@ -7,7 +7,10 @@ select_args_text <- function(fun, select = "", topic) { select_args(fun, parsed) }, error = function(e) { - warn_roxy_tag(topic, "failed to parse argument specification", parent = e) + cli::cli_warn( + "@inheritDotsParam failed in topic {.str {topic$get_name()}}.", + parent = e + ) character() } ) diff --git a/R/tag-metadata.R b/R/tag-metadata.R index ac97dda7..aca7464b 100644 --- a/R/tag-metadata.R +++ b/R/tag-metadata.R @@ -25,7 +25,7 @@ tags_metadata <- function() { tag = map_chr(meta, "name"), description = map_chr(meta, "description"), # \n not useful outside of RStudio - template = sub("\n", "", map_chr(meta, "template")), + template = sub("\n", "", map_chr(meta, "template", .default = "")), vignette = map_chr(meta, "vignette", .default = NA), recommend = map_lgl(meta, "recommend", .default = FALSE), stringsAsFactors = FALSE diff --git a/R/utils.R b/R/utils.R index d5ac6125..bb0b9696 100644 --- a/R/utils.R +++ b/R/utils.R @@ -103,10 +103,10 @@ same_contents <- function(path, contents) { } if (!file.exists(path)) return(FALSE) - text_hash <- digest::digest(contents, serialize = FALSE) + text_hash <- cli::hash_sha256(contents) path <- normalizePath(path, mustWork = TRUE) - file_hash <- digest::digest(file = path) + file_hash <- cli::hash_file_sha256(path) identical(text_hash, file_hash) } @@ -164,11 +164,6 @@ uuid <- function(nchar = 8) { ) } -# https://github.com/r-lib/rlang/issues/1434 -is_installed <- function(x) { - !identical(system.file(package = x), "") -} - # quoting ----------------------------------------------------------------- auto_backtick <- function(x) { needs_backtick <- !has_quotes(x) & !is_syntactic(x) diff --git a/README.md b/README.md index 43eef07d..177c8f75 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# roxygen2 +# roxygen2 [![CRAN status](https://www.r-pkg.org/badges/version/roxygen2)](https://CRAN.R-project.org/package=roxygen2) @@ -11,12 +11,12 @@ The premise of roxygen2 is simple: describe your functions in comments next to t ## Installation ```R -# Install devtools from CRAN +# Install roxygen2 from CRAN install.packages("roxygen2") # Or the development version from GitHub: -# install.packages("devtools") -devtools::install_github("r-lib/roxygen2") +# install.packages("pak") +pak::pak("r-lib/roxygen2") ``` ## Usage diff --git a/cran-comments.md b/cran-comments.md index 63a02eaa..ae5c3aa0 100644 --- a/cran-comments.md +++ b/cran-comments.md @@ -3,13 +3,4 @@ There were no ERRORs, WARNINGs or NOTEs. ## revdepcheck results -We checked 344 reverse dependencies, comparing R CMD check results across CRAN and dev versions of this package. - - * We saw 0 new problems - * We failed to check 1 packages - -Issues with CRAN packages are summarised below. - -### Failed to check - -* valse (NA) +This was a documentation change to fix an HTML tidy issue; I did not check revdeps. diff --git a/inst/roxygen2-tags.yml b/inst/roxygen2-tags.yml index a825914f..f562557a 100644 --- a/inst/roxygen2-tags.yml +++ b/inst/roxygen2-tags.yml @@ -1,36 +1,37 @@ - name: aliases description: > - Add additional aliases to the topic. Use `NULL` to suppress - the default alias automatically generated by roxygen2. - template: ' {alias}' + Add additional aliases to the topic. + + Use `NULL` to suppress the default alias automatically generated by roxygen2. + template: ' ${1:alias}' vignette: index-crossref recommend: true - name: author description: > Topic author(s), if different from the package author(s). - template: ' {author}' + template: ' ${1:author}' recommend: true - name: backref description: > Manually override the backreference that points from the `.Rd` file back to the source `.R` file. Only needed when generating code. - template: ' {path}' + template: ' ${1:path}' vignette: index-crossref - name: concept description: > Add additional keywords or phrases to be included in the `help.search()` index. Each `@concept` should be a single term or phrase. - template: ' {concept}' + template: ' ${1:concept}' vignette: index-crossref recommend: true - name: describeIn description: > Document a function or method in the `destination` topic. - template: ' {destination} {description}' + template: ' ${1:destination} ${2:description}' vignette: reuse recommend: true @@ -38,7 +39,7 @@ description: > A short description of the purpose of the function. Usually around a paragraph, but can be longer if needed. - template: "\n" + template: "\n${1:A short description...}\n" vignette: rd recommend: true @@ -46,46 +47,47 @@ description: > Additional details about the function. Generally superseded by instead using a level 1 heading. - template: "\n" + template: "\n${1:Additional details...}\n" vignette: rd - name: docType description: > Set documentation type. One of `data`, `package`, `class`, or `methods`. + Usually added automatically; for expert use only. - template: ' data|package|class|methods' + template: ' ${1:data|package|class|methods}' - name: encoding description: > Override encoding of single `.Rd` file. No longer recommended since all documentation should use UTF-8. - template: ' {encoding}' + template: ' ${1:encoding}' - name: eval description: > Evaluate arbitrary code in the package namespace and insert the results back into the block. Should return a character vector of lines. - template: ' {r-code}' + template: ' ${1:r-code}' vignette: reuse - name: evalNamespace description: > Evaluate arbitrary code in the package namespace and insert the results into the `NAMESPACE`. Should return a character vector of directives. - template: ' {r-code}' + template: ' ${1:r-code}' vignette: namespace - name: evalRd description: > Evaluate arbitrary code in the package namespace and insert the results back as into the block. Should return a character vector of lines. - template: ' {r-code}' + template: ' ${1:r-code}' vignette: reuse - name: example description: > Embed examples stored in another file. - template: ' {path}' + template: ' ${1:path}.R' vignette: rd recommend: true @@ -93,14 +95,14 @@ description: > Executable R code that demonstrates how the function works. Code must run without error. - template: "\n" + template: "\n${1:# example code}\n" vignette: rd recommend: true - name: examplesIf description: > Run examples only when `condition` is `TRUE`. - template: " {condition}\n" + template: " ${1:condition}\n${1:# example code}\n" vignette: rd recommend: true @@ -108,7 +110,6 @@ description: > Export this function, method, generic, or class so it's available outside of the package. - template: "" vignette: namespace recommend: true @@ -116,41 +117,41 @@ description: > Export an S4 class. For expert use only; in most cases you should use `@export` so roxygen2 can automatically generate the correct directive. - template: ' {class}' + template: ' ${1:class}' vignette: namespace - name: exportMethod description: > Export S4 methods. For expert use only; in most cases you should use `@export` so roxygen2 can automatically generate the correct directive. - template: ' {generic}' + template: ' ${1:generic}' vignette: namespace - name: exportPattern description: > Export all objects matching a regular expression. - template: ' {pattern}' + template: ' ${1:pattern}' vignette: namespace - name: exportS3Method description: > Export an S3 method. Only needed when the method is for a generic from a suggested package. - template: ' pkg::generic' + template: ' ${1:package}::${2:generic}' vignette: namespace recommend: true - name: family description: > Generate `@seealso` entries to all other functions in `family name`. - template: ' {family name}' + template: ' ${1:family name}' vignette: index-crossref recommend: true - name: field description: > Describe a R6 or refClass field. - template: ' {name} {description}' + template: ' ${1:name} ${2:description}' vignette: rd-other recommend: true @@ -159,56 +160,57 @@ Describe the type/shape of a dataset. If the dataset is a data frame, include a description of each column. If not supplied, will be automatically generated by `object_format()`. - template: ' {description}' + template: ' ${1:description}' vignette: rd-other recommend: true - name: import description: > Import all functions from a package. Use with extreme care. - template: ' {package}' + template: ' ${1:package}' vignette: namespace - name: importClassesFrom description: > Import S4 classes from another package. - template: ' {package} {class}' + template: ' ${1:package} ${2:class}' vignette: namespace - name: importFrom description: > Import specific functions from a package. - template: ' {package} {function}' + template: ' ${1:package} ${2:function}' vignette: namespace recommend: true - name: importMethodsFrom description: > Import S4 methods from a package. - template: ' {package} {generic}' + template: ' ${1:package} ${2:generic}' vignette: namespace - name: include description: > Declare that `filename.R` must be loaded before the current file. - template: ' {filename.R}' + template: ' ${1:filename}.R' recommend: true - name: includeRmd description: > Insert the contents of an `.Rmd` into the current block. Superseded in favour of using a code chunk with a child document. - template: ' {path}' + template: ' man/rmd/${1:filename}.Rmd' vignette: reuse - name: inherit description: > Inherit one or more documentation components from another topic. If `components` is omitted, all supported components will be inherited. + Otherwise, specify individual components to inherit by picking one or more of `params`, `return`, `title`, `description`, `details`, `seealso`, `sections`, `references`, `examples`, `author`, `source`, and `note`. - template: ' {source} {components}' + template: ' ${1:source} ${2:components}' vignette: reuse recommend: true @@ -216,7 +218,7 @@ description: > Automatically generate documentation for `...` when you're passing dots along to another function. - template: ' {source} {arg1 arg2 arg3}' + template: ' ${1:source} ${2:arg1 arg2 arg3}' vignette: reuse recommend: true @@ -224,14 +226,14 @@ description: > Inherit argument documentation from another function. Only inherits documentation for arguments that aren't already documented locally. - template: ' {source}' + template: ' ${1:source}' vignette: reuse recommend: true - name: inheritSection description: > Inherit a specific named section from another topic. - template: ' {source} {section name}' + template: ' ${1:source} ${2:section name}' vignette: reuse recommend: true @@ -240,14 +242,13 @@ Add a standardised keyword, indexed by `help.search()`. These are generally not useful apart from `@keyword internal` which flags the topic as internal and removes from topic indexes. - template: ' {keyword}' + template: ' ${1:keyword}' vignette: index-crossref recommend: true - name: md description: > Force markdown processing for a block. - template: '' vignette: rd-formatting - name: method @@ -255,27 +256,26 @@ Force a function to be recognised as an S3 method. This affects the default usage and the `NAMESPACE` directive produced by `@export`. Only needed if automatic detection fails. - template: ' {generic} {class}' + template: ' ${1:generic} ${2:class}' vignette: rd-other recommend: true - name: name description: > - Define (or override the topic) name. Typically only needed for synthetic - topics where you are documenting `NULL`. - template: ' {name}' + Define (or override the topic) name. + + Typically only needed for synthetic topics where you are documenting `NULL`. + template: ' ${1:name}' - name: noMd description: > Suppress markdown processing for a block. - template: '' vignette: 'rd-formatting' - name: noRd description: > - Suppress `.Rd` generation for a block. Use for documentation blocks that - should only be visible in the source code. - template: '' + Suppress `.Rd` generation for a block. Use for documentation + blocks that should only be visible in the source code. vignette: 'rd' recommend: true @@ -289,7 +289,7 @@ description: > Override the default (lexigraphic) order in which multiple blocks are combined into a single topic. - template: ' {number}' + template: ' ${1:number}' vignette: reuse recommend: true @@ -297,43 +297,45 @@ description: > Describe a function input. Should describe acceptable input types and how it affects the output. `description` is usually one or two - sentences but can be as long as needed. Document multiple arguments - by separating their names with commas without spaces. - template: ' {name} {description}' + sentences but can be as long as needed. + + Document multiple arguments by separating their names with commas + without spaces. + template: ' ${1:name} ${2:description}' vignette: rd recommend: true - name: rawNamespace description: > Insert literal text directly into the `NAMESPACE`. - template: ' {namespace directives}' + template: ' ${1:namespace directives}' vignette: namespace - name: rawRd description: > Insert literal text directly into the `.Rd` file. - template: ' {rd}' + template: ' ${1:rd}' vignette: rd - name: rdname description: > Override the file name of generated `.Rd` file. Can be used to combine multiple blocks into a single documentation topic. - template: ' {topic-name}' + template: ' ${1:topic-name}' vignette: reuse recommend: true - name: references description: > Pointers to the related literature. Usually formatted like a bibliography. - template: ' {reference}' + template: ' ${1:reference}' vignette: index-crossref recommend: true - name: return description: > Describe the function's output. Superseded in favour of `@returns`. - template: ' {description}' + template: ' ${1:description}' vignette: rd - name: returns @@ -341,7 +343,7 @@ Describe the function's output. Typically will be a 1-2 sentence description of the output type, but might also include discussion of important errors or warnings. - template: ' {description}' + template: ' ${1:description}' vignette: rd recommend: true @@ -349,21 +351,21 @@ description: > Add an arbitrary section to the documentation. Now generally superseded in favour of using a level 1 heading. - template: " {section title}:\n" + template: " ${1:section title}: \n" vignette: rd-formatting - name: seealso description: > Link to other related functions or urls. Usually a sentence or two, or a bulleted list. - template: ' {[func1()], }' + template: ' [${1:func}()]' vignette: index-crossref recommend: true - name: slot description: > Describe the slot of an S4 class. - template: ' {name} {description}' + template: ' ${1:name} ${2:description}' vignette: rd-other recommend: true @@ -372,20 +374,20 @@ Describe where the dataset came from. Provide a link to the original source (if possible) and briefly describe any manipulation that you performed when importing the data. - template: ' {description}' + template: ' ${1:description}' vignette: rd-other recommend: true - name: template description: > Use a roxygen2 template. Now superseded in favour of inline R code. - template: ' {path-to-template}' + template: ' ${1:path-to-template}' vignette: reuse - name: templateVar description: > Define variables for use in a roxygen2 template. - template: ' {name} {value}' + template: ' ${1:name} ${2:value}' vignette: reuse - name: title @@ -393,7 +395,7 @@ A one-line description of the function shown in various indexes. An explicit `@title` is not usually needed as by default it is taken from the first paragraph in the roxygen block. - template: ' {title}' + template: ' ${1:title}' vignette: rd recommend: true @@ -401,13 +403,13 @@ description: > Override the default usage generated by roxygen2. Only needed when roxygen2 fails to correctly derive the usage of your function. - template: ' {function_call(arg1, arg2 = default, ...)}' + template: ' ${1:fun}(${2:arg1, arg2 = default, ...})' vignette: rd recommend: true - name: useDynLib description: > Import compiled code from another package. - template: ' {package}' + template: ' ${1:package}' vignette: namespace recommend: true diff --git a/man/figures/logo.png b/man/figures/logo.png index 2188d2ce..0ab90d76 100644 Binary files a/man/figures/logo.png and b/man/figures/logo.png differ diff --git a/man/roxy_block.Rd b/man/roxy_block.Rd index 96ded757..a85ffad6 100644 --- a/man/roxy_block.Rd +++ b/man/roxy_block.Rd @@ -31,7 +31,7 @@ by inspecting/evaluating \code{call}.} \item{block}{A \code{roxy_block} to manipulate.} -\item{tag, tags}{Either a single tag name, or a character vector of tag names.} +\item{tag}{A single tag name.} } \description{ A \code{roxy_block} represents a single roxygen2 block. diff --git a/man/tags-index-crossref.Rd b/man/tags-index-crossref.Rd index 9aad721a..87df6d9d 100644 --- a/man/tags-index-crossref.Rd +++ b/man/tags-index-crossref.Rd @@ -11,30 +11,31 @@ \alias{@seealso} \title{Tags for indexing and cross-references} \usage{ -#' @aliases {alias} -#' @backref {path} -#' @concept {concept} -#' @family {family name} -#' @keywords {keyword} -#' @references {reference} -#' @seealso {[func1()], } +#' @aliases ${1:alias} +#' @backref ${1:path} +#' @concept ${1:concept} +#' @family ${1:family name} +#' @keywords ${1:keyword} +#' @references ${1:reference} +#' @seealso [${1:func}()] } \description{ Learn full the details in in \code{vignette('index-crossref')}. Key tags: \itemize{ -\item \verb{@aliases \{alias\}}: Add additional aliases to the topic. Use \code{NULL} to suppress the default alias automatically generated by roxygen2. -\item \verb{@concept \{concept\}}: Add additional keywords or phrases to be included in the \code{help.search()} index. Each \verb{@concept} should be a single term or phrase. -\item \verb{@family \{family name\}}: Generate \verb{@seealso} entries to all other functions in \verb{family name}. -\item \verb{@keywords \{keyword\}}: Add a standardised keyword, indexed by \code{help.search()}. These are generally not useful apart from \verb{@keyword internal} which flags the topic as internal and removes from topic indexes. -\item \verb{@references \{reference\}}: Pointers to the related literature. Usually formatted like a bibliography. -\item \verb{@seealso \{[func1()], \}}: Link to other related functions or urls. Usually a sentence or two, or a bulleted list. +\item \verb{@aliases $\{1:alias\}}: Add additional aliases to the topic. +Use \code{NULL} to suppress the default alias automatically generated by roxygen2. +\item \verb{@concept $\{1:concept\}}: Add additional keywords or phrases to be included in the \code{help.search()} index. Each \verb{@concept} should be a single term or phrase. +\item \verb{@family $\{1:family name\}}: Generate \verb{@seealso} entries to all other functions in \verb{family name}. +\item \verb{@keywords $\{1:keyword\}}: Add a standardised keyword, indexed by \code{help.search()}. These are generally not useful apart from \verb{@keyword internal} which flags the topic as internal and removes from topic indexes. +\item \verb{@references $\{1:reference\}}: Pointers to the related literature. Usually formatted like a bibliography. +\item \verb{@seealso [$\{1:func\}()]}: Link to other related functions or urls. Usually a sentence or two, or a bulleted list. } Other less frequently used tags: \itemize{ -\item \verb{@backref \{path\}}: Manually override the backreference that points from the \code{.Rd} file back to the source \code{.R} file. Only needed when generating code. +\item \verb{@backref $\{1:path\}}: Manually override the backreference that points from the \code{.Rd} file back to the source \code{.R} file. Only needed when generating code. } } \seealso{ diff --git a/man/tags-namespace.Rd b/man/tags-namespace.Rd index 3ba3d116..52ca97b3 100644 --- a/man/tags-namespace.Rd +++ b/man/tags-namespace.Rd @@ -16,18 +16,18 @@ \alias{@useDynLib} \title{Tags for managing the \code{NAMESPACE}} \usage{ -#' @evalNamespace {r-code} +#' @evalNamespace ${1:r-code} #' @export -#' @exportClass {class} -#' @exportMethod {generic} -#' @exportPattern {pattern} -#' @exportS3Method pkg::generic -#' @import {package} -#' @importClassesFrom {package} {class} -#' @importFrom {package} {function} -#' @importMethodsFrom {package} {generic} -#' @rawNamespace {namespace directives} -#' @useDynLib {package} +#' @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} } \description{ Learn full the details in in \code{vignette('namespace')}. @@ -35,20 +35,20 @@ Learn full the details in in \code{vignette('namespace')}. Key tags: \itemize{ \item \verb{@export}: Export this function, method, generic, or class so it's available outside of the package. -\item \verb{@exportS3Method pkg::generic}: Export an S3 method. Only needed when the method is for a generic from a suggested package. -\item \verb{@importFrom \{package\} \{function\}}: Import specific functions from a package. -\item \verb{@useDynLib \{package\}}: Import compiled code from another package. +\item \verb{@exportS3Method $\{1:package\}::$\{2:generic\}}: Export an S3 method. Only needed when the method is for a generic from a suggested package. +\item \verb{@importFrom $\{1:package\} $\{2:function\}}: Import specific functions from a package. +\item \verb{@useDynLib $\{1:package\}}: Import compiled code from another package. } Other less frequently used tags: \itemize{ -\item \verb{@evalNamespace \{r-code\}}: Evaluate arbitrary code in the package namespace and insert the results into the \code{NAMESPACE}. Should return a character vector of directives. -\item \verb{@exportClass \{class\}}: Export an S4 class. For expert use only; in most cases you should use \verb{@export} so roxygen2 can automatically generate the correct directive. -\item \verb{@exportMethod \{generic\}}: Export S4 methods. For expert use only; in most cases you should use \verb{@export} so roxygen2 can automatically generate the correct directive. -\item \verb{@exportPattern \{pattern\}}: Export all objects matching a regular expression. -\item \verb{@import \{package\}}: Import all functions from a package. Use with extreme care. -\item \verb{@importClassesFrom \{package\} \{class\}}: Import S4 classes from another package. -\item \verb{@importMethodsFrom \{package\} \{generic\}}: Import S4 methods from a package. -\item \verb{@rawNamespace \{namespace directives\}}: Insert literal text directly into the \code{NAMESPACE}. +\item \verb{@evalNamespace $\{1:r-code\}}: Evaluate arbitrary code in the package namespace and insert the results into the \code{NAMESPACE}. Should return a character vector of directives. +\item \verb{@exportClass $\{1:class\}}: Export an S4 class. For expert use only; in most cases you should use \verb{@export} so roxygen2 can automatically generate the correct directive. +\item \verb{@exportMethod $\{1:generic\}}: Export S4 methods. For expert use only; in most cases you should use \verb{@export} so roxygen2 can automatically generate the correct directive. +\item \verb{@exportPattern $\{1:pattern\}}: Export all objects matching a regular expression. +\item \verb{@import $\{1:package\}}: Import all functions from a package. Use with extreme care. +\item \verb{@importClassesFrom $\{1:package\} $\{2:class\}}: Import S4 classes from another package. +\item \verb{@importMethodsFrom $\{1:package\} $\{2:generic\}}: Import S4 methods from a package. +\item \verb{@rawNamespace $\{1:namespace directives\}}: Insert literal text directly into the \code{NAMESPACE}. } } diff --git a/man/tags-rd-formatting.Rd b/man/tags-rd-formatting.Rd index 771db56a..f58d9246 100644 --- a/man/tags-rd-formatting.Rd +++ b/man/tags-rd-formatting.Rd @@ -9,7 +9,7 @@ \usage{ #' @md #' @noMd -#' @section {section title}: +#' @section ${1:section title}: } \description{ Learn full the details in in \code{vignette('rd-formatting')}. @@ -18,6 +18,6 @@ Other less frequently used tags: \itemize{ \item \verb{@md}: Force markdown processing for a block. \item \verb{@noMd}: Suppress markdown processing for a block. -\item \verb{@section \{section title\}:}: Add an arbitrary section to the documentation. Now generally superseded in favour of using a level 1 heading. +\item \verb{@section $\{1:section title\}: }: Add an arbitrary section to the documentation. Now generally superseded in favour of using a level 1 heading. } } diff --git a/man/tags-rd-other.Rd b/man/tags-rd-other.Rd index 1dfc4f47..594682bd 100644 --- a/man/tags-rd-other.Rd +++ b/man/tags-rd-other.Rd @@ -9,22 +9,22 @@ \alias{@source} \title{Tags for documenting datasets and classes} \usage{ -#' @field {name} {description} -#' @format {description} -#' @method {generic} {class} -#' @slot {name} {description} -#' @source {description} +#' @field ${1:name} ${2:description} +#' @format ${1:description} +#' @method ${1:generic} ${2:class} +#' @slot ${1:name} ${2:description} +#' @source ${1:description} } \description{ Learn full the details in in \code{vignette('rd-other')}. Key tags: \itemize{ -\item \verb{@field \{name\} \{description\}}: Describe a R6 or refClass field. -\item \verb{@format \{description\}}: Describe the type/shape of a dataset. If the dataset is a data frame, include a description of each column. If not supplied, will be automatically generated by \code{object_format()}. -\item \verb{@method \{generic\} \{class\}}: Force a function to be recognised as an S3 method. This affects the default usage and the \code{NAMESPACE} directive produced by \verb{@export}. Only needed if automatic detection fails. -\item \verb{@slot \{name\} \{description\}}: Describe the slot of an S4 class. -\item \verb{@source \{description\}}: Describe where the dataset came from. Provide a link to the original source (if possible) and briefly describe any manipulation that you performed when importing the data. +\item \verb{@field $\{1:name\} $\{2:description\}}: Describe a R6 or refClass field. +\item \verb{@format $\{1:description\}}: Describe the type/shape of a dataset. If the dataset is a data frame, include a description of each column. If not supplied, will be automatically generated by \code{object_format()}. +\item \verb{@method $\{1:generic\} $\{2:class\}}: Force a function to be recognised as an S3 method. This affects the default usage and the \code{NAMESPACE} directive produced by \verb{@export}. Only needed if automatic detection fails. +\item \verb{@slot $\{1:name\} $\{2:description\}}: Describe the slot of an S4 class. +\item \verb{@source $\{1:description\}}: Describe where the dataset came from. Provide a link to the original source (if possible) and briefly describe any manipulation that you performed when importing the data. } } \seealso{ diff --git a/man/tags-rd.Rd b/man/tags-rd.Rd index 72a958b7..cc0fcf2a 100644 --- a/man/tags-rd.Rd +++ b/man/tags-rd.Rd @@ -16,40 +16,45 @@ \alias{@usage} \title{Tags for documenting functions} \usage{ -#' @description -#' @details -#' @example {path} -#' @examples -#' @examplesIf {condition} +#' @description${1:A short description...} + +#' @details${1:Additional details...} + +#' @example ${1:path}.R +#' @examples${1:# example code} + +#' @examplesIf ${1:condition}${1:# example code} + #' @noRd -#' @param {name} {description} -#' @rawRd {rd} -#' @return {description} -#' @returns {description} -#' @title {title} -#' @usage {function_call(arg1, arg2 = default, ...)} +#' @param ${1:name} ${2:description} +#' @rawRd ${1:rd} +#' @return ${1:description} +#' @returns ${1:description} +#' @title ${1:title} +#' @usage ${1:fun}(${2:arg1, arg2 = default, ...}) } \description{ Learn full the details in in \code{vignette('rd')}. Key tags: \itemize{ -\item \verb{@description}: A short description of the purpose of the function. Usually around a paragraph, but can be longer if needed. -\item \verb{@example \{path\}}: Embed examples stored in another file. -\item \verb{@examples}: Executable R code that demonstrates how the function works. Code must run without error. -\item \verb{@examplesIf \{condition\}}: Run examples only when \code{condition} is \code{TRUE}. +\item \verb{@description$\{1:A short description...\} }: A short description of the purpose of the function. Usually around a paragraph, but can be longer if needed. +\item \verb{@example $\{1:path\}.R}: Embed examples stored in another file. +\item \verb{@examples$\{1:# example code\} }: Executable R code that demonstrates how the function works. Code must run without error. +\item \verb{@examplesIf $\{1:condition\}$\{1:# example code\} }: Run examples only when \code{condition} is \code{TRUE}. \item \verb{@noRd}: Suppress \code{.Rd} generation for a block. Use for documentation blocks that should only be visible in the source code. -\item \verb{@param \{name\} \{description\}}: Describe a function input. Should describe acceptable input types and how it affects the output. \code{description} is usually one or two sentences but can be as long as needed. Document multiple arguments by separating their names with commas without spaces. -\item \verb{@returns \{description\}}: Describe the function's output. Typically will be a 1-2 sentence description of the output type, but might also include discussion of important errors or warnings. -\item \verb{@title \{title\}}: A one-line description of the function shown in various indexes. An explicit \verb{@title} is not usually needed as by default it is taken from the first paragraph in the roxygen block. -\item \verb{@usage \{function_call(arg1, arg2 = default, ...)\}}: Override the default usage generated by roxygen2. Only needed when roxygen2 fails to correctly derive the usage of your function. +\item \verb{@param $\{1:name\} $\{2:description\}}: Describe a function input. Should describe acceptable input types and how it affects the output. \code{description} is usually one or two sentences but can be as long as needed. +Document multiple arguments by separating their names with commas without spaces. +\item \verb{@returns $\{1:description\}}: Describe the function's output. Typically will be a 1-2 sentence description of the output type, but might also include discussion of important errors or warnings. +\item \verb{@title $\{1:title\}}: A one-line description of the function shown in various indexes. An explicit \verb{@title} is not usually needed as by default it is taken from the first paragraph in the roxygen block. +\item \verb{@usage $\{1:fun\}($\{2:arg1, arg2 = default, ...\})}: Override the default usage generated by roxygen2. Only needed when roxygen2 fails to correctly derive the usage of your function. } Other less frequently used tags: \itemize{ -\item \verb{@details}: Additional details about the function. Generally superseded by instead using a level 1 heading. -\item \verb{@rawRd \{rd\}}: Insert literal text directly into the \code{.Rd} file. -\item \verb{@return \{description\}}: Describe the function's output. Superseded in favour of \verb{@returns}. +\item \verb{@details$\{1:Additional details...\} }: Additional details about the function. Generally superseded by instead using a level 1 heading. +\item \verb{@rawRd $\{1:rd\}}: Insert literal text directly into the \code{.Rd} file. +\item \verb{@return $\{1:description\}}: Describe the function's output. Superseded in favour of \verb{@returns}. } } \seealso{ diff --git a/man/tags-reuse.Rd b/man/tags-reuse.Rd index a95c7d41..ddb69f87 100644 --- a/man/tags-reuse.Rd +++ b/man/tags-reuse.Rd @@ -16,40 +16,41 @@ \alias{@templateVar} \title{Tags that help you reuse documentation} \usage{ -#' @describeIn {destination} {description} -#' @eval {r-code} -#' @evalRd {r-code} -#' @includeRmd {path} -#' @inherit {source} {components} -#' @inheritDotParams {source} {arg1 arg2 arg3} -#' @inheritParams {source} -#' @inheritSection {source} {section name} -#' @order {number} -#' @rdname {topic-name} -#' @template {path-to-template} -#' @templateVar {name} {value} +#' @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} } \description{ Learn full the details in in \code{vignette('reuse')}. Key tags: \itemize{ -\item \verb{@describeIn \{destination\} \{description\}}: Document a function or method in the \code{destination} topic. -\item \verb{@inherit \{source\} \{components\}}: Inherit one or more documentation components from another topic. If \code{components} is omitted, all supported components will be inherited. Otherwise, specify individual components to inherit by picking one or more of \code{params}, \code{return}, \code{title}, \code{description}, \code{details}, \code{seealso}, \code{sections}, \code{references}, \code{examples}, \code{author}, \code{source}, and \code{note}. -\item \verb{@inheritDotParams \{source\} \{arg1 arg2 arg3\}}: Automatically generate documentation for \code{...} when you're passing dots along to another function. -\item \verb{@inheritParams \{source\}}: Inherit argument documentation from another function. Only inherits documentation for arguments that aren't already documented locally. -\item \verb{@inheritSection \{source\} \{section name\}}: Inherit a specific named section from another topic. -\item \verb{@order \{number\}}: Override the default (lexigraphic) order in which multiple blocks are combined into a single topic. -\item \verb{@rdname \{topic-name\}}: Override the file name of generated \code{.Rd} file. Can be used to combine multiple blocks into a single documentation topic. +\item \verb{@describeIn $\{1:destination\} $\{2:description\}}: Document a function or method in the \code{destination} topic. +\item \verb{@inherit $\{1:source\} $\{2:components\}}: Inherit one or more documentation components from another topic. If \code{components} is omitted, all supported components will be inherited. +Otherwise, specify individual components to inherit by picking one or more of \code{params}, \code{return}, \code{title}, \code{description}, \code{details}, \code{seealso}, \code{sections}, \code{references}, \code{examples}, \code{author}, \code{source}, and \code{note}. +\item \verb{@inheritDotParams $\{1:source\} $\{2:arg1 arg2 arg3\}}: Automatically generate documentation for \code{...} when you're passing dots along to another function. +\item \verb{@inheritParams $\{1:source\}}: Inherit argument documentation from another function. Only inherits documentation for arguments that aren't already documented locally. +\item \verb{@inheritSection $\{1:source\} $\{2:section name\}}: Inherit a specific named section from another topic. +\item \verb{@order $\{1:number\}}: Override the default (lexigraphic) order in which multiple blocks are combined into a single topic. +\item \verb{@rdname $\{1:topic-name\}}: Override the file name of generated \code{.Rd} file. Can be used to combine multiple blocks into a single documentation topic. } Other less frequently used tags: \itemize{ -\item \verb{@eval \{r-code\}}: Evaluate arbitrary code in the package namespace and insert the results back into the block. Should return a character vector of lines. -\item \verb{@evalRd \{r-code\}}: Evaluate arbitrary code in the package namespace and insert the results back as into the block. Should return a character vector of lines. -\item \verb{@includeRmd \{path\}}: Insert the contents of an \code{.Rmd} into the current block. Superseded in favour of using a code chunk with a child document. -\item \verb{@template \{path-to-template\}}: Use a roxygen2 template. Now superseded in favour of inline R code. -\item \verb{@templateVar \{name\} \{value\}}: Define variables for use in a roxygen2 template. +\item \verb{@eval $\{1:r-code\}}: Evaluate arbitrary code in the package namespace and insert the results back into the block. Should return a character vector of lines. +\item \verb{@evalRd $\{1:r-code\}}: Evaluate arbitrary code in the package namespace and insert the results back as into the block. Should return a character vector of lines. +\item \verb{@includeRmd man/rmd/$\{1:filename\}.Rmd}: Insert the contents of an \code{.Rmd} into the current block. Superseded in favour of using a code chunk with a child document. +\item \verb{@template $\{1:path-to-template\}}: Use a roxygen2 template. Now superseded in favour of inline R code. +\item \verb{@templateVar $\{1:name\} $\{2:value\}}: Define variables for use in a roxygen2 template. } } \seealso{ diff --git a/revdep/cran.md b/revdep/cran.md index 86705541..ff31c447 100644 --- a/revdep/cran.md +++ b/revdep/cran.md @@ -1,12 +1,3 @@ ## revdepcheck results -We checked 344 reverse dependencies, comparing R CMD check results across CRAN and dev versions of this package. - - * We saw 0 new problems - * We failed to check 1 packages - -Issues with CRAN packages are summarised below. - -### Failed to check - -* valse (NA) +We did not check reverse dependencies, since this is a small patch release. diff --git a/tests/testthat/_snaps/markdown-code.md b/tests/testthat/_snaps/markdown-code.md index a1eee718..ef824123 100644 --- a/tests/testthat/_snaps/markdown-code.md +++ b/tests/testthat/_snaps/markdown-code.md @@ -19,8 +19,11 @@ Condition Warning: [:4] @description failed to evaluate inline markdown code - Caused by error in `parse()`: - ! :2:0: unexpected end of input + Caused by error in `map_chr()`: + i In index: 1. + Caused by error: + ! Failed to parse the inline R code: `r 1 + ` + Reason: :2:0: unexpected end of input 1: 1 + ^ diff --git a/tests/testthat/_snaps/markdown.md b/tests/testthat/_snaps/markdown.md index e93b25b2..4f844e01 100644 --- a/tests/testthat/_snaps/markdown.md +++ b/tests/testthat/_snaps/markdown.md @@ -16,6 +16,28 @@ After +# can insert block and inline html + + Code + out$get_section("description") + Output + \description{ + \if{html}{\out{ +

This is a paragraph

+

This is another paragraph

+ }} + } + +--- + + Code + out$get_section("description") + Output + \description{ + This is a paragraph containing a manually inserted image + before-\if{html}{\out{}}-after + } + # can convert table to Rd Code diff --git a/tests/testthat/_snaps/object-r6.md b/tests/testthat/_snaps/object-r6.md index 60af9c0d..d05fa768 100644 --- a/tests/testthat/_snaps/object-r6.md +++ b/tests/testthat/_snaps/object-r6.md @@ -3,7 +3,10 @@ Code extract_r6_data(C) Condition - Error: + Error in `map_int()`: + i In index: 1. + i With name: meth1. + Caused by error: ! R6 class lacks source references. i If you are using the `installed` load method in `DESCRIPTION`, then try re-installing the package with option '--with-keep.source', e.g. `install.packages(..., INSTALL_OPTS = "--with-keep.source")`. diff --git a/tests/testthat/_snaps/rd-include-rmd.md b/tests/testthat/_snaps/rd-include-rmd.md index 7659174d..b26a53fd 100644 --- a/tests/testthat/_snaps/rd-include-rmd.md +++ b/tests/testthat/_snaps/rd-include-rmd.md @@ -4,7 +4,14 @@ --- - [:3] @includeRmd failed to evaluate Rmd - Caused by error: - ! Error + Code + . <- roc_proc_text(rd_roclet(), text) + Message + Quitting from lines 2-3 () + Quitting from lines 2-3 () + Condition + Warning: + [:3] @includeRmd failed to evaluate '' + Caused by error: + ! Error diff --git a/tests/testthat/_snaps/rd-inherit.md b/tests/testthat/_snaps/rd-inherit.md index c9dd4152..0b12c378 100644 --- a/tests/testthat/_snaps/rd-inherit.md +++ b/tests/testthat/_snaps/rd-inherit.md @@ -39,6 +39,16 @@ }} } +# useful error for bad inherits + + Code + . <- roc_proc_text(rd_roclet(), text) + Condition + Warning: + @inheritDotsParam failed in topic "bar". + Caused by error in `FUN()`: + ! object 'z' not found + # useful warnings if can't find topics Code diff --git a/tests/testthat/_snaps/rd-template.md b/tests/testthat/_snaps/rd-template.md index d052bb97..32857ff8 100644 --- a/tests/testthat/_snaps/rd-template.md +++ b/tests/testthat/_snaps/rd-template.md @@ -3,6 +3,8 @@ Code roc_proc_text(rd_roclet(), block) Condition - Error: + Error in `map_chr()`: + i In index: 1. + Caused by error: ! Can't find template "doesn't-exist" diff --git a/tests/testthat/_snaps/select-args.md b/tests/testthat/_snaps/select-args.md index f5ef1dab..f5599a79 100644 --- a/tests/testthat/_snaps/select-args.md +++ b/tests/testthat/_snaps/select-args.md @@ -1,10 +1,10 @@ # warns on invalid input Code - select_args_text(sum, "-xlab:", tag) + select_args_text(sum, "-xlab:", topic) Condition Warning: - [test.R:1] @test failed to parse argument specification + @inheritDotsParam failed in topic "test". Caused by error in `parse()`: ! :2:0: unexpected end of input 1: -xlab: @@ -12,20 +12,20 @@ Output character(0) Code - select_args_text(sum, "\"a\"", tag) + select_args_text(sum, "\"a\"", topic) Condition Warning: - [test.R:1] @test failed to parse argument specification + @inheritDotsParam failed in topic "test". Caused by error in `select_check()`: ! Argument specification must evaluate to a numeric vector Problem in `"a"` Output character(0) Code - select_args_text(function(x, y, z) { }, "-x:z", tag) + select_args_text(function(x, y, z) { }, "-x:z", topic) Condition Warning: - [test.R:1] @test failed to parse argument specification + @inheritDotsParam failed in topic "test". Caused by error: ! Argument specification must be all positive or all negative, not a mixture i Problem in `-x:z` diff --git a/tests/testthat/test-markdown.R b/tests/testthat/test-markdown.R index 7eed1c61..b516623e 100644 --- a/tests/testthat/test-markdown.R +++ b/tests/testthat/test-markdown.R @@ -204,6 +204,28 @@ test_that("nested lists are OK", { }) +# html -------------------------------------------------------------------- + +test_that("can insert block and inline html", { + out <- roc_proc_text(rd_roclet(), " + #' Title + #' + #'

This is a paragraph

+ #'

This is another paragraph

+ #' @md + foo <- function() {}")[[1]] + expect_snapshot(out$get_section("description")) + + out <- roc_proc_text(rd_roclet(), " + #' Title + #' + #' This is a paragraph containing a manually inserted image + #' before--after + #' @md + foo <- function() {}")[[1]] + expect_snapshot(out$get_section("description")) +}) + # tables ------------------------------------------------------------------ diff --git a/tests/testthat/test-rd-include-rmd.R b/tests/testthat/test-rd-include-rmd.R index 42932b5d..90cd08ea 100644 --- a/tests/testthat/test-rd-include-rmd.R +++ b/tests/testthat/test-rd-include-rmd.R @@ -271,11 +271,31 @@ test_that("useful warnings", { "stop('Error')", "```" )) + path <- normalizePath(path) + text <- sprintf(" #' Title #' @includeRmd %s #' @name foobar NULL", path ) - expect_snapshot_warning(roc_proc_text(rd_roclet(), text)) + expect_snapshot( + . <- roc_proc_text(rd_roclet(), text), + transform = function(x) gsub(path, "", x, fixed =TRUE) + ) +}) + +test_that("sets width", { + skip_if_not(rmarkdown::pandoc_available("2.17")) + + local_options(width = 123) + temp_rd <- withr::local_tempfile(lines = "`r getOption('width')`") + + rox <- sprintf(" + #' Title + #' @includeRmd %s + #' @name foobar + NULL", temp_rd) + out <- roc_proc_text(rd_roclet(), rox)[[1]] + expect_equal(out$get_value("details"), "80") }) diff --git a/tests/testthat/test-rd-inherit.R b/tests/testthat/test-rd-inherit.R index eb393978..a9e16a41 100644 --- a/tests/testthat/test-rd-inherit.R +++ b/tests/testthat/test-rd-inherit.R @@ -675,6 +675,23 @@ test_that("inheritDotParams does not add already-documented params", { expect_match(dot_param, "item{\\code{z}}{z description}", fixed = TRUE) }) +test_that("useful error for bad inherits", { + text <- " + #' Foo + #' + #' @param x x + #' @param y y + foo <- function(x, y) {} + + #' Bar + #' + #' @inheritDotParams foo -z + bar <- function(...) {} + " + expect_snapshot(. <- roc_proc_text(rd_roclet(), text)) +}) + + # inherit everything ------------------------------------------------------ test_that("can inherit all from single function", { diff --git a/tests/testthat/test-select-args.R b/tests/testthat/test-select-args.R index 5ac19163..8e15b6b2 100644 --- a/tests/testthat/test-select-args.R +++ b/tests/testthat/test-select-args.R @@ -1,10 +1,11 @@ test_that("warns on invalid input", { - tag <- roxy_test_tag() + topic <- RoxyTopic$new() + topic$add(rd_section("name", "test")) expect_snapshot({ - select_args_text(sum, "-xlab:", tag) - select_args_text(sum, '"a"', tag) - select_args_text(function(x, y, z) {}, "-x:z", tag) + select_args_text(sum, "-xlab:", topic) + select_args_text(sum, '"a"', topic) + select_args_text(function(x, y, z) {}, "-x:z", topic) }) }) diff --git a/vignettes/index-crossref.Rmd b/vignettes/index-crossref.Rmd index 5b55d876..e15a64a0 100644 --- a/vignettes/index-crossref.Rmd +++ b/vignettes/index-crossref.Rmd @@ -1,12 +1,12 @@ --- -title: "Indexing and cross-refernces" +title: "Indexing and cross-references" output: rmarkdown::html_vignette description: > Make it easier for users to find your functions by cross-referencing them and control their indexing. vignette: > - %\VignetteIndexEntry{Indexing and cross-refernces} + %\VignetteIndexEntry{Indexing and cross-references} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} ---