Skip to content

fix(r-cran-extrachecks): exempt @export-only S3 methods from docs checks - #95

Merged
gadenbuie merged 2 commits into
mainfrom
fix/63-cran-extrachecks-clarify-rules-on-exported-generic-functions
Oct 7, 2026
Merged

gadenbuie merged 2 commits into
mainfrom
fix/63-cran-extrachecks-clarify-rules-on-exported-generic-functions

Conversation

@gadenbuie

Copy link
Copy Markdown
Collaborator

Summary

Clarifies the r-cran-extrachecks skill's documentation rules so it stops flagging exported S3 methods that are documented only with #' @export as missing @return/@examples (reported in #63).

Roxygen2 only generates an .Rd file when a block contains documentation content. A block with only #' @export adds the function to the NAMESPACE without producing an .Rd, so CRAN's documentation checks have nothing to inspect. R CMD check's undocumented-objects check also excludes registered S3 methods, so the conventional print.my_class() pattern passes as-is.

What changed

  • Return value documentation: added an "applies only to functions with an .Rd file" clarification with the print.my_class() example, plus guardrails:
    • The exemption holds only while the block contains nothing but @export/@exportS3Method — adding any documentation content (title, @param, @rdname, @describeIn) makes roxygen2 generate an .Rd and all rules apply again
    • Newly exported S3 generics are ordinary documented exported functions and still need @return/@examples
    • Methods sharing a page via @rdname/@describeIn follow the generic's rules — required tags once per .Rd
  • Examples section: matching bullet pointing to the exemption
  • Workflow step 5: notes the exemption during the initial documentation pass
  • Checklist: reworded two items to key off .Rd files; added items for the S3-method exemption and S3-generics-with-full-docs checks

Skill remains within token limits (475 lines, ~3.9k tokens).

Fixes #63

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
@gadenbuie gadenbuie changed the title fix(r-cran-extrachecks): exempt @export-only S3 methods from docs checks fix(r-cran-extrachecks): exempt @export-only S3 methods from docs checks Oct 7, 2026
@gadenbuie
gadenbuie merged commit e20b71b into main Oct 7, 2026
1 check passed
@gadenbuie
gadenbuie deleted the fix/63-cran-extrachecks-clarify-rules-on-exported-generic-functions branch October 7, 2026 17:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

cran-extrachecks: clarify rules on exported generic functions

1 participant