Specify the use of #' @Keywords internal (#918)

* Specify the use of `#' @Keywords internal`

* Move mention of devtag to the end of the paragraph.

* Update descripion of internal function doc tags

* Update wording

* add translations

* news

* Update pkg_building.pt.Rmd

Co-authored-by: Francesca Palmeira <francesca@alumni.usp.br>

* Update pkg_building.es.Rmd

---------

Co-authored-by: Maëlle Salmon <maelle.salmon@yahoo.se>
Co-authored-by: Francesca Palmeira <francesca@alumni.usp.br>
Co-authored-by: Yanina Bellini Saibene <yabellini@gmail.com>

Author: 4 people

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).

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 <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.
 

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 <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 su documentación. Si no quieres que se genere documentación de la función, utiliza `#' noRd` en su lugar. Consulta la documentación de [`roxygen2`  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`.
 

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 <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`. 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`.