Skip to content

Specify the use of #' @keywords internal #918

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Specify the use of #' @keywords internal #918

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
1c9b78b
Specify the use of `#' @keywords internal`
cforgaci Jul 9, 2025
625c0a6
Move mention of devtag to the end of the paragraph.
cforgaci Jul 9, 2025
10a112f
Update descripion of internal function doc tags
cforgaci Jul 9, 2025
62b0999
Update wording
cforgaci Sep 13, 2025
3ddf0f8
add translations
maelle Oct 17, 2025
51e7c0f
news
maelle Oct 17, 2025
f4b19d2
Update pkg_building.pt.Rmd
maelle Nov 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions booknews.Rmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
2 changes: 1 addition & 1 deletion pkg_building.Rmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -253,7 +253,7 @@ f <- function(a = TRUE) {

- For including examples, you can use the classic `@examples` tag (plural "examples") but also the `@example <path>` 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 `#' @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.

Expand Down
6 changes: 1 addition & 5 deletions pkg_building.es.Rmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <path>` (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`.

Expand Down Expand Up @@ -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).
Expand Down Expand Up @@ -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.


2 changes: 1 addition & 1 deletion pkg_building.pt.Rmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <path>` (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`.

Expand Down