From f0cf0da8f370dc89a8b77df8dc2244ed79c00e8a Mon Sep 17 00:00:00 2001 From: Garrick Aden-Buie Date: Wed, 7 Oct 2026 13:31:50 -0400 Subject: [PATCH 1/2] fix(r-cran-extrachecks): exempt @export-only S3 methods from docs checks Roxygen2 blocks containing only `#' @export` generate no .Rd file, so there is nothing for CRAN documentation checks to inspect. Registered S3 methods are also excluded from R CMD check's undocumented-objects check, so methods following the `print.my_class()` pattern do not need `@return` or `@examples`. Clarify the skill's documentation rules, examples guidance, workflow step, and checklist to reflect this. Also note that the exemption is void once any documentation content is added to the block, and that newly exported S3 generics still require full documentation. Fixes #63 --- r-lib/r-cran-extrachecks/SKILL.md | 25 ++++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/r-lib/r-cran-extrachecks/SKILL.md b/r-lib/r-cran-extrachecks/SKILL.md index ba36d40..f000818 100644 --- a/r-lib/r-cran-extrachecks/SKILL.md +++ b/r-lib/r-cran-extrachecks/SKILL.md @@ -33,7 +33,7 @@ Work through these items systematically: - Does the README clearly explain the package purpose and functionality? - **Important**: If README.Rmd exists, edit ONLY README.Rmd (README.md will be overwritten), then run `devtools::build_readme()` to re-render README.md 4. **Proofread DESCRIPTION**: Carefully review `Title:` and `Description:` fields (see detailed guidance below) -5. **Check function documentation**: Verify all exported functions have `@return` and `@examples` (see detailed guidance below) +5. **Check function documentation**: Verify all exported functions have `@return` and `@examples` (see detailed guidance below). Note the exemption for S3 methods documented only with `#' @export`: they produce no `.Rd` file and are not required to have either tag 6. **Verify copyright holder**: Check that `Authors@R:` includes a copyright holder with role `[cph]` 7. **Review bundled file licensing**: Check licensing of any included third-party files 8. **Run URL checks**: Use `urlchecker::url_check()` and fix any issues @@ -50,6 +50,22 @@ CRAN now strictly requires `@return` documentation for all exported functions. U - Required even if function returns nothing - document as `@return None` or similar - Must be present for every exported function +These rules apply only to functions with an `.Rd` file. Roxygen2 creates an `.Rd` file only when a block contains documentation content (a title or description). A block that contains nothing but `#' @export` adds the function to the `NAMESPACE` without generating an `.Rd` file, so there is nothing for CRAN's documentation checks to inspect. This is the conventional pattern for S3 methods: + +```r +#' @export +print.my_class <- function(x, ...) { + cat("my_class object\n") + invisible(x) +} +``` + +Such methods do **not** need `@return` or `@examples`, and `R CMD check` does not flag them as undocumented (registered S3 methods are excluded from the undocumented-objects check). + +- The exemption holds only while the block contains *nothing but* `@export` (or `@exportS3Method`). Adding a title, `@param`, `@rdname`, `@describeIn`, or any other documentation makes roxygen2 generate an `.Rd` file, and the function must then satisfy all documentation rules including `@return`. +- Do not confuse these with the S3 *generic* itself (e.g., `my_print <- function(x, ...) UseMethod("my_print")`). A newly exported generic is an ordinary exported function with documentation, so it still needs `@return` and `@examples`. +- Methods sharing a page with their generic via `@rdname` or `@describeIn` follow the same rules as the generic: the combined `.Rd` needs the required tags once, not once per method. + Example: ```r # Missing @return - WILL BE REJECTED @@ -86,6 +102,7 @@ If your exported function has a meaningful return value, it will almost definite - Required even for functions marked `@keywords internal` - Exceptions exist for functions used purely for side effects (e.g., creating directories) - Examples must be executable +- S3 methods with `@export`-only roxygen blocks have no `.Rd` file and need no examples (see above) **Un-exported Functions with Examples** @@ -446,8 +463,10 @@ Use this checklist to ensure nothing is missed before submission: - [ ] LICENSE year matches current submission year ### Function Documentation -- [ ] All exported functions have `@return` documentation -- [ ] All exported functions with meaningful returns have `@examples` +- [ ] All exported functions with `.Rd` files have `@return` documentation +- [ ] All documented exported functions with meaningful returns have `@examples` +- [ ] S3 methods with `@export`-only roxygen blocks are correctly exempt (no `.Rd` file, no `@return`/`@examples` needed) +- [ ] S3 generics added by the package have full documentation (`@return`, `@examples`) since they are ordinary exported functions - [ ] No example sections use commented-out code - [ ] Examples avoid `\dontrun{}` unless truly necessary - [ ] Examples requiring suggested packages use `@examplesIf` or `if` guards From 88fc26c352cceb12580d819472682eda5deefb6a Mon Sep 17 00:00:00 2001 From: Garrick Aden-Buie Date: Wed, 7 Oct 2026 13:35:17 -0400 Subject: [PATCH 2/2] chore(r-cran-extrachecks): bump skill version to 1.1 --- r-lib/r-cran-extrachecks/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/r-lib/r-cran-extrachecks/SKILL.md b/r-lib/r-cran-extrachecks/SKILL.md index f000818..7a59a4c 100644 --- a/r-lib/r-cran-extrachecks/SKILL.md +++ b/r-lib/r-cran-extrachecks/SKILL.md @@ -4,7 +4,7 @@ description: > Prepare R packages for CRAN submission by checking for common ad-hoc requirements not caught by devtools::check(). Use when: (1) Preparing a package for first CRAN release, (2) Preparing a package update for CRAN resubmission, (3) Reviewing a package to ensure CRAN compliance, (4) Responding to CRAN reviewer feedback. Covers documentation requirements, DESCRIPTION field standards, URL validation, examples, and administrative requirements. metadata: author: Garrick Aden-Buie (@gadenbuie) - version: "1.0" + version: "1.1" license: MIT ---