Specify the use of #' @keywords internal
#918
Conversation
|
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
Then say if you don't want any fn docs generated at all, use |
|
@mpadge I updated the text as you suggest. I also removed
It is good a use case of |
|
@maelle I've approved here -feel free to suggest any additional tweaks, otherwise please merge ✔️ |
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`. |
There was a problem hiding this comment.
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. 😇
There was a problem hiding this comment.
@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.
|
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
requested review from
fblpalmeira and
yabellini
and removed request for
a team
| - 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`. |
There was a problem hiding this comment.
| - 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` 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`. |
4 participants
@mpadge, @maelle, I made a suggestion as a folow-up to our discussion in ropensci/statistical-software-review-book#44 (comment)
I hope this helps.