From 1c9b78b9e5b3b52c26c40efadc5bf934daf5c94a Mon Sep 17 00:00:00 2001 From: Claudiu Forgaci Date: Wed, 9 Jul 2025 10:33:17 +0200 Subject: [PATCH 1/7] 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 af01dab8d..2622043f0 100644 --- a/pkg_building.Rmd +++ b/pkg_building.Rmd @@ -253,7 +253,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 625c0a67ffb9caac4d29ebd698bf5e91e6ddd72f Mon Sep 17 00:00:00 2001 From: Claudiu Forgaci Date: Wed, 9 Jul 2025 10:39:22 +0200 Subject: [PATCH 2/7] 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 2622043f0..0f0774308 100644 --- a/pkg_building.Rmd +++ b/pkg_building.Rmd @@ -253,7 +253,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 10a112fcec4deed4863468520fbe8a0b5ead925b Mon Sep 17 00:00:00 2001 From: Claudiu Forgaci Date: Wed, 9 Jul 2025 11:11:44 +0200 Subject: [PATCH 3/7] 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 0f0774308..5365d3f7e 100644 --- a/pkg_building.Rmd +++ b/pkg_building.Rmd @@ -253,7 +253,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. From 62b0999490cebf5ca8620c83050d9b0b619536d3 Mon Sep 17 00:00:00 2001 From: Claudiu Forgaci Date: Sat, 13 Sep 2025 21:34:29 +0200 Subject: [PATCH 4/7] Update wording --- pkg_building.Rmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkg_building.Rmd b/pkg_building.Rmd index 5365d3f7e..9a83dcf0a 100644 --- a/pkg_building.Rmd +++ b/pkg_building.Rmd @@ -253,7 +253,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 `#' @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`. +- Add `#' @keywords internal` to mark a function as internal while still 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. From 3ddf0f89aa43347b93a4133d618a16d3353bca14 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ma=C3=ABlle=20Salmon?= Date: Fri, 17 Oct 2025 10:31:24 +0200 Subject: [PATCH 5/7] add translations --- pkg_building.es.Rmd | 6 +----- pkg_building.pt.Rmd | 2 +- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/pkg_building.es.Rmd b/pkg_building.es.Rmd index b983e1913..16b0f2f23 100644 --- a/pkg_building.es.Rmd +++ b/pkg_building.es.Rmd @@ -280,8 +280,7 @@ f <- function(a = TRUE) { - Para incluir ejemplos, puedes utilizar el clásico `@examples` (en plural *"examples"*), pero también la etiqueta `@example ` (en singular *"example"*) para almacenar el código de ejemplo en un script R independiente (idealmente en `man/`), y la etiqueta `@exampleIf` para ejecutar ejemplos condicionalmente y evitar fallos de `R CMD check`. Consulta [la documentación de roxygen2 sobre ejemplos](https://roxygen2.r-lib.org/articles/rd.html#examples). -- Añade `#' @noRd` a las funciones internas. Quizá te interese el [paquete experimental devtag](https://github.com/moodymudskipper/devtag) para obtener páginas de manual locales al utilizar `#' @noRd`. - +- Añade `#' @keywords internal` para marcar una función como interna sin dejar de generar documentación para ella. Si no quieres que se genere ninguna documentación de la función, utiliza `#' noRd` en su lugar. Consulta [`roxygen2` documentación sobre etiquetas para indexación y referencias cruzadas](https://roxygen2.r-lib.org/reference/tags-index-crossref.html) y [etiquetas para documentar funciones](https://roxygen2.r-lib.org/reference/tags-rd.html). Para fines de desarrollo, puede que te interese la etiqueta [paquete experimental devtag](https://github.com/moodymudskipper/devtag) para obtener páginas de manual locales al utilizar `#' @noRd`. - A partir de la versión 7.0.0 de roxygen2, las clases `R6` son oficialmente compatibles. Consulta la [documentación de roxygen2](https://roxygen2.r-lib.org/articles/rd-other.html#r6) para saber cómo documentar las clases `R6`. @@ -324,7 +323,6 @@ Esto te ahorrará el trabajo de ejecutar (y acordarte de ejecutar) `pkgdown::bui Consulta nuestro [capítulo sobre integración continua](#ci) si ésto no te resulta familiar. En cualquier caso, no olvides actualizar la URL del sitio web en todos los lados donde aparezca después de hacer la transferencia a la organización ropensci. - ### Idioma Si la documentación de tu paquete está escrita en un idioma distinto del inglés (pero compatible con el sistema de revisión de software por pares de rOpenSci), puedes declarar ese idioma para que el sitio web pkgdown se [localice](https://pkgdown.r-lib.org/articles/translations.html). @@ -639,5 +637,3 @@ Si deseas que tu paquete se envíe a Bioconductor, o si tu paquete está en Bioc #### MOOCs {#moo-cs} Existe una [especialización en Coursera correspondiente al libro de Roger Peng, Sean Kross y Brooke Anderson](https://fr.coursera.org/specializations/r) con un curso específico sobre paquetes de R. - - diff --git a/pkg_building.pt.Rmd b/pkg_building.pt.Rmd index b3891a52e..7bb1596ff 100644 --- a/pkg_building.pt.Rmd +++ b/pkg_building.pt.Rmd @@ -253,7 +253,7 @@ f <- function(a = TRUE) { - Para incluir exemplos, você pode usar o clássico `@examples` (no plural *"examples"*), mas também a tag `@example ` (no singular *"example"*) para armazenar o código de exemplo em um script R separado (de preferência na pasta `man/`), e a tag `@exampleIf` para executar exemplos condicionalmente e evitar falhas na verificação do R CMD. Consulte a [documentação do roxygen2 sobre exemplos](https://roxygen2.r-lib.org/articles/rd.html#examples). -- Adicionar `#' @noRd` às funções internas. Talvez você se interesse no [pacote experimental devtag](https://github.com/moodymudskipper/devtag) para obter páginas de manual locais ao usar `#' @noRd`. +- Adicionar `#' @keywords internal` para marcar uma função como interna e, ao mesmo tempo, gerar documentação para ela. Se você não quiser que nenhuma documentação de função seja gerada, use `#' noRd` em vez disso. Consulte [`roxygen2` documentação sobre tags para indexação e referência cruzada](https://roxygen2.r-lib.org/reference/tags-index-crossref.html) e [tags para funções de documentação](https://roxygen2.r-lib.org/reference/tags-rd.html). Para fins de desenvolvimento, você pode se interessar pelo [pacote experimental devtag](https://github.com/moodymudskipper/devtag) para obter páginas de manual locais ao usar o `#' @noRd`. - A partir da versão 7.0.0 do roxygen2, as classes `R6` são oficialmente suportadas. Consulte a [documentação do roxygen2](https://roxygen2.r-lib.org/articles/rd-other.html#r6) para obter detalhes sobre como documentar classes `R6`. From 51e7c0fa568d333dd9dbc75cc1bb6c404c97fe7a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ma=C3=ABlle=20Salmon?= Date: Fri, 17 Oct 2025 10:44:08 +0200 Subject: [PATCH 6/7] news --- booknews.Rmd | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/booknews.Rmd b/booknews.Rmd index cf523c5b8..0d6cff930 100644 --- a/booknews.Rmd +++ b/booknews.Rmd @@ -2,6 +2,10 @@ ## dev version +- 2025-10-17, clarify the use of Rd tags for internal functions (#918, `@cforgaci`). + +- 2025-10-09, add translation of the last chapter to Portuguese! + - 2025-09-23, Add section on challenges (non-responding reviewers). Also move text on non-responding authors to this section. (#955). - 2025-07-11, document better when the pkgdown websites of rOpenSci packages are re-built (#919). From f4b19d2f124ce4fe1ce3f7d2105ebe3a285698b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ma=C3=ABlle=20Salmon?= Date: Mon, 3 Nov 2025 10:12:29 +0100 Subject: [PATCH 7/7] Update pkg_building.pt.Rmd Co-authored-by: Francesca Palmeira --- pkg_building.pt.Rmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkg_building.pt.Rmd b/pkg_building.pt.Rmd index 7bb1596ff..7dc0a08f6 100644 --- a/pkg_building.pt.Rmd +++ b/pkg_building.pt.Rmd @@ -253,7 +253,7 @@ f <- function(a = TRUE) { - Para incluir exemplos, você pode usar o clássico `@examples` (no plural *"examples"*), mas também a tag `@example ` (no singular *"example"*) para armazenar o código de exemplo em um script R separado (de preferência na pasta `man/`), e a tag `@exampleIf` para executar exemplos condicionalmente e evitar falhas na verificação do R CMD. Consulte a [documentação do roxygen2 sobre exemplos](https://roxygen2.r-lib.org/articles/rd.html#examples). -- Adicionar `#' @keywords internal` para marcar uma função como interna e, ao mesmo tempo, gerar documentação para ela. Se você não quiser que nenhuma documentação de função seja gerada, use `#' noRd` em vez disso. Consulte [`roxygen2` documentação sobre tags para indexação e referência cruzada](https://roxygen2.r-lib.org/reference/tags-index-crossref.html) e [tags para funções de documentação](https://roxygen2.r-lib.org/reference/tags-rd.html). Para fins de desenvolvimento, você pode se interessar pelo [pacote experimental devtag](https://github.com/moodymudskipper/devtag) para obter páginas de manual locais ao usar o `#' @noRd`. +- Adicionar `#' @keywords internal` para marcar uma função como interna e, ao mesmo tempo, gerar documentação para ela. Se você não quiser que nenhuma documentação de função seja gerada, use `#' noRd`. Consulte [a documentação do `roxygen2` sobre tags para indexação e referência cruzada](https://roxygen2.r-lib.org/reference/tags-index-crossref.html) e [tags para funções de documentação](https://roxygen2.r-lib.org/reference/tags-rd.html). Para fins de desenvolvimento, você pode se interessar pelo [pacote experimental devtag](https://github.com/moodymudskipper/devtag) para obter páginas de manual locais ao usar o `#' @noRd`. - A partir da versão 7.0.0 do roxygen2, as classes `R6` são oficialmente suportadas. Consulte a [documentação do roxygen2](https://roxygen2.r-lib.org/articles/rd-other.html#r6) para obter detalhes sobre como documentar classes `R6`.