Specify the use of `#' @keywords internal` #918

That's great @cforgaci, and thanks for responding so promptly. Can you may rearrange the sentence, especially to avoid starting with a negative implication, "aren't worth documenting ...". I think it would be better to first suggest @keywords internal, with a description of what that does (might be best to quote and link to roxygen2 docs:

flags the topic as internal and removes from topic indexes

Then say if you don't want any fn docs generated at all, use @noRd.

@cforgaci

Copy link

Author

cforgaci commented Jul 9, 2025 •

edited

Loading

@mpadge I updated the text as you suggest. I also removed

Note that functions with #' @keywords internal do not require an #' @example section for CRAN submission.

It is good a use case of #' @keywords internal, but it might be an unnecessary side note here.

@mpadge mpadge self-requested a review

July 9, 2025 09:21

mpadge

mpadge approved these changes

Jul 9, 2025

View reviewed changes

Copy link

Member

@mpadge mpadge left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks great, thanks @cforgaci

@mpadge

Copy link

Member

mpadge commented Jul 9, 2025

@maelle I've approved here -feel free to suggest any additional tweaks, otherwise please merge ✔️

maelle

maelle reviewed

Jul 9, 2025

View reviewed changes

pkg_building.Rmd Outdated

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

Copy link

Member

@maelle maelle Jul 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure I agree. Could we clarify "flag the function as internal"? It won't be flagged to users who somehow stumble on the docs, but it won't be included in the reference index.

I actually wonder whether we should be put devtag more upfront as it's a good compromise, even if it is not on CRAN and a bit experimental.

@mpadge also note that we can't merge PRs as is any longer, we first need to generate translations and have them reviewed. 😇

Copy link

Author

@cforgaci cforgaci Sep 13, 2025 •

edited

Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@maelle thank you for the feedback and apologies for the very late reaction. I replaced "flag" with "mark" to avoid confusion, although I don't think that solves your concern. For me, the order in which the options are presented now makes most sense, with the first two occurring most often, and devtag used less common. I think the devtag README also describes the differences between the three options very clearly. However, please feel free to discard my suggestion if you do not agree with it.

@maelle

Copy link

Member

maelle commented Sep 23, 2025

I do like the change as it is now, thank you! I'll wait for #952 to be merged before adding translations to this PR. Thanks for your patience.

@maelle maelle added this to the 1.0.0 milestone

Sep 23, 2025

cforgaci added 4 commits

October 17, 2025 10:22

@cforgaci @maelle


 Specify the use of #' @Keywords internal

1c9b78b

@cforgaci @maelle


 Move mention of devtag to the end of the paragraph.

625c0a6

@cforgaci @maelle


 Update descripion of internal function doc tags

10a112f

@cforgaci @maelle


 Update wording

62b0999

@maelle maelle force-pushed the main branch from fc33964 to 62b0999 Compare

October 17, 2025 08:22

@maelle


 add translations

3ddf0f8

@maelle maelle requested review from a team as code owners

October 17, 2025 08:31

@maelle maelle requested review from fblpalmeira and yabellini and removed request for a team

October 17, 2025 08:31

@maelle


 news

51e7c0f

beatrizmilz

beatrizmilz reviewed

Oct 26, 2025

View reviewed changes

pkg_building.pt.Rmd

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

Copy link

Contributor

@beatrizmilz beatrizmilz Oct 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change

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

Copy link

Contributor

@fblpalmeira fblpalmeira Oct 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change

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

Copy link

Contributor

@fblpalmeira fblpalmeira Oct 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@beatrizmilz, achei que o trecho "em vez disso" ficou confuso. Na versão em espanhol está "em seu lugar" e na em inglês não tem essa parte. Achei que em português sem nada fluiu melhor.

fblpalmeira

fblpalmeira approved these changes

Oct 31, 2025

View reviewed changes

Copy link

Contributor

@fblpalmeira fblpalmeira left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@beatrizmilz fiz uma pequena alteração, veja se faz sentido.

pkg_building.pt.Rmd

Copy link

Contributor

@fblpalmeira fblpalmeira Oct 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change

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

pkg_building.pt.Rmd

Copy link

Contributor

@fblpalmeira fblpalmeira Oct 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@beatrizmilz, achei que o trecho "em vez disso" ficou confuso. Na versão em espanhol está "em seu lugar" e na em inglês não tem essa parte. Achei que em português sem nada fluiu melhor.

Labels

None yet

5 participants

@cforgaci @mpadge @maelle @beatrizmilz @fblpalmeira

Specify the use of #' @keywords internal #918

Are you sure you want to change the base?

Specify the use of #' @keywords internal #918

Uh oh!

Conversation

@cforgaci cforgaci commented Jul 9, 2025

Uh oh!

mpadge commented Jul 9, 2025

Uh oh!

cforgaci commented Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

@mpadge mpadge left a comment

Choose a reason for hiding this comment

Uh oh!

mpadge commented Jul 9, 2025

Uh oh!

@maelle maelle Jul 9, 2025

Choose a reason for hiding this comment

Uh oh!

@cforgaci cforgaci Sep 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

maelle commented Sep 23, 2025

Uh oh!

@beatrizmilz beatrizmilz Oct 26, 2025

Choose a reason for hiding this comment

Uh oh!

@fblpalmeira fblpalmeira Oct 31, 2025

Choose a reason for hiding this comment

Uh oh!

@fblpalmeira fblpalmeira Oct 31, 2025

Choose a reason for hiding this comment

Uh oh!

@fblpalmeira fblpalmeira left a comment

Choose a reason for hiding this comment

Uh oh!

@fblpalmeira fblpalmeira Oct 31, 2025

Choose a reason for hiding this comment

Uh oh!

@fblpalmeira fblpalmeira Oct 31, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Specify the use of `#' @keywords internal` #918

Specify the use of `#' @keywords internal` #918

cforgaci commented Jul 9, 2025 •

edited

Loading

@cforgaci cforgaci Sep 13, 2025 •

edited

Loading