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 3 commits into
base: main
Choose a base branch
from
Open

Specify the use of #' @keywords internal #918

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bad4ed8
Specify the use of `#' @keywords internal`
cforgaci Jul 9, 2025
2e86730
Move mention of devtag to the end of the paragraph.
cforgaci Jul 9, 2025
224a2c6
Update descripion of internal function doc tags
cforgaci Jul 9, 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
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 @@ -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`.
Copy link
Member

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


- 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