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 ✔️ |
| @@ -252,7 +252,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 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. 😇
@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.