From bad4ed8d4dfdf52816c95d3c2ba55ee20c4660fa Mon Sep 17 00:00:00 2001 From: Claudiu Forgaci Date: Wed, 9 Jul 2025 10:33:17 +0200 Subject: [PATCH 1/3] Specify the use of `#' @keywords internal` --- pkg_building.Rmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkg_building.Rmd b/pkg_building.Rmd index 93414cfe9..d5123cd2c 100644 --- a/pkg_building.Rmd +++ b/pkg_building.Rmd @@ -252,7 +252,7 @@ f <- function(a = TRUE) { - For including examples, you can use the classic `@examples` tag (plural "examples") but also the `@example ` tag (singular "example") for storing the example code in a separate R script (ideally under `man/`), and the `@exampleIf` tag for running examples conditionally and avoiding R CMD check failures. Refer to [roxygen2 documentation about examples](https://roxygen2.r-lib.org/articles/rd.html#examples). -- Add `#' @noRd` to internal functions. You might be interested in the [devtag experimental package](https://github.com/moodymudskipper/devtag) for getting local manual pages when using `#' @noRd`. +- Add `#' @noRd` to internal functions that aren't worth documenting for end users. For development purposes, you might be interested in the [devtag experimental package](https://github.com/moodymudskipper/devtag) for getting local manual pages when using `#' @noRd`. If you want to build documentation for certain internal functions, you can use `#' @keywords internal` instead of `#' @noRd`. Note that functions with `#' @keywords internal` do not require an `#' @example` section for CRAN submission. - Starting from roxygen2 version 7.0.0, `R6` classes are officially supported. See the [roxygen2 docs](https://roxygen2.r-lib.org/articles/rd-other.html#r6) for details on how to document `R6` classes. From 2e86730fae4c4685693fdafe1807b2f8e27de9dd Mon Sep 17 00:00:00 2001 From: Claudiu Forgaci Date: Wed, 9 Jul 2025 10:39:22 +0200 Subject: [PATCH 2/3] Move mention of devtag to the end of the paragraph. --- pkg_building.Rmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkg_building.Rmd b/pkg_building.Rmd index d5123cd2c..1bfd7914f 100644 --- a/pkg_building.Rmd +++ b/pkg_building.Rmd @@ -252,7 +252,7 @@ f <- function(a = TRUE) { - For including examples, you can use the classic `@examples` tag (plural "examples") but also the `@example ` tag (singular "example") for storing the example code in a separate R script (ideally under `man/`), and the `@exampleIf` tag for running examples conditionally and avoiding R CMD check failures. Refer to [roxygen2 documentation about examples](https://roxygen2.r-lib.org/articles/rd.html#examples). -- Add `#' @noRd` to internal functions that aren't worth documenting for end users. For development purposes, you might be interested in the [devtag experimental package](https://github.com/moodymudskipper/devtag) for getting local manual pages when using `#' @noRd`. If you want to build documentation for certain internal functions, you can use `#' @keywords internal` instead of `#' @noRd`. Note that functions with `#' @keywords internal` do not require an `#' @example` section for CRAN submission. +- Add `#' @noRd` to internal functions that aren't worth documenting for end users. If you want to build documentation for certain internal functions, you can use `#' @keywords internal` instead of `#' @noRd`. Note that functions with `#' @keywords internal` do not require an `#' @example` section for CRAN submission. For development purposes, you might be interested in the [devtag experimental package](https://github.com/moodymudskipper/devtag) for getting local manual pages when using `#' @noRd`. - Starting from roxygen2 version 7.0.0, `R6` classes are officially supported. See the [roxygen2 docs](https://roxygen2.r-lib.org/articles/rd-other.html#r6) for details on how to document `R6` classes. From 224a2c6576a090e7786ab7986dc0065a77bdb97f Mon Sep 17 00:00:00 2001 From: Claudiu Forgaci Date: Wed, 9 Jul 2025 11:11:44 +0200 Subject: [PATCH 3/3] Update descripion of internal function doc tags --- pkg_building.Rmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkg_building.Rmd b/pkg_building.Rmd index 1bfd7914f..1a13614f0 100644 --- a/pkg_building.Rmd +++ b/pkg_building.Rmd @@ -252,7 +252,7 @@ f <- function(a = TRUE) { - For including examples, you can use the classic `@examples` tag (plural "examples") but also the `@example ` tag (singular "example") for storing the example code in a separate R script (ideally under `man/`), and the `@exampleIf` tag for running examples conditionally and avoiding R CMD check failures. Refer to [roxygen2 documentation about examples](https://roxygen2.r-lib.org/articles/rd.html#examples). -- Add `#' @noRd` to internal functions that aren't worth documenting for end users. If you want to build documentation for certain internal functions, you can use `#' @keywords internal` instead of `#' @noRd`. Note that functions with `#' @keywords internal` do not require an `#' @example` section for CRAN submission. For development purposes, you might be interested in the [devtag experimental package](https://github.com/moodymudskipper/devtag) for getting local manual pages when using `#' @noRd`. +- Add `#' @keywords internal` to flag the function as internal while generating documentation for it. If you do not want any function documentation generated at all, use `#' noRd` instead. Refer to [`roxygen2` documentation about tags for indexing and cross-referencing](https://roxygen2.r-lib.org/reference/tags-index-crossref.html) and [tags for documenting functions](https://roxygen2.r-lib.org/reference/tags-rd.html). For development purposes, you might be interested in the [devtag experimental package](https://github.com/moodymudskipper/devtag) for getting local manual pages when using `#' @noRd`. - Starting from roxygen2 version 7.0.0, `R6` classes are officially supported. See the [roxygen2 docs](https://roxygen2.r-lib.org/articles/rd-other.html#r6) for details on how to document `R6` classes.