undefined

**Examples for Exported Functions**

If your exported function has a meaningful return value, it will almost definitely require an `@examples` section. Use the roxygen2 tag `@examples`.

- Required even for functions marked `@keywords internal`
- Exceptions exist for functions used purely for side effects (e.g., creating directories)
- Examples must be executable

**Un-exported Functions with Examples**

If you write roxygen examples for un-exported functions, you must either:

1. Call them with `:::` notation: `pkg:::my_fun()`
2. Use `@noRd` tag to suppress `.Rd` file creation

**Using `\dontrun{}` Sparingly**

`\dontrun{}` should only be used if the example really cannot be executed (e.g., missing additional software, API keys, etc.).

- If showing an error, wrap the call in `try()` instead
- Consider custom predicates (e.g., `googlesheets4::sheets_has_token()`) with `if ()` blocks
- Sometimes `interactive()` can be used as the condition
- Lengthy examples (> 5 sec) can use `\donttest{}`

**Never Comment Out Code in Examples**

```r

CRAN's guidance: "Examples/code lines in examples should never be commented out. Ideally find toy examples that can be regularly executed and checked."

**Guarding Examples with Suggested Packages**

Use `@examplesIf` for entire example sections requiring suggested packages:

```r
#' @examplesIf rlang::is_installed("dplyr")
#' library(dplyr)
#' my_data %>% my_function()

#' @examples
#' if (rlang::is_installed("dplyr")) {
#'   library(dplyr)
#'   my_data %>% my_function()
#' }

undefined

**Quote Software/Package Names**

Put all software and R package names in single quotes:

```r

**Length Limit**

Keep titles under 65 characters.

undefined

**Expand to 3-4 Sentences**

Single-sentence descriptions are insufficient. Provide a broader description of:
- What the package does
- Why it may be useful
- Types of problems it helps solve

```r

**Quote Software Names, Not Functions**

```r

Software, package, and API names get single quotes (including 'R'). Function names do not.

**Expand All Acronyms**

All acronyms must be fully expanded on first mention:

```r

**Publication Titles Only in Double Quotes**

Only use double quotes for publication titles, not for phrases or emphasis:

```r

undefined

undefined

**No Redirecting URLs**

CRAN rejects URLs that redirect to other locations. Example rejection:

**Use urlchecker Package**

```r

**Ignore URLs That Will Exist After Publication**

Some URLs that don't currently resolve will exist once the package is published on CRAN. These should NOT be changed:

- CRAN badge URLs (e.g., `https://cran.r-project.org/package=pkgname`)
- CRAN status badges (e.g., `https://www.r-pkg.org/badges/version/pkgname`)
- CRAN check results (e.g., `https://cranchecks.info/badges/pkgname`)
- Package documentation URLs on r-universe or pkgdown sites that deploy after release

When `urlchecker::url_check()` flags these URLs, leave them as-is. They are aspirational URLs that will work once the package is on CRAN.

**Check for Invalid File URIs**

Relative links in README must exist after package build. Common issue:

This occurs when files are in `.Rbuildignore`. Solutions:
1. Remove file from `.Rbuildignore`
2. Use `usethis::use_code_of_conduct()` which generates sections without relative links

undefined

**Posit-Supported Packages**

For packages in Posit-related GitHub organizations (posit-dev, rstudio, r-lib, tidyverse, tidymodels) or maintained by someone with a @posit.co email address, include Posit Software, PBC as copyright holder and funder:

```r
Authors@R: c(
  person("Jane", "Doe", role = c("aut", "cre"),
         email = "jane.doe@posit.co"),
  person("Posit Software, PBC", role = c("cph", "fnd"),
         comment = c(ROR = "03wc8by49"))
)

undefined

**Method References**

CRAN may ask:

> If there are references describing the methods in your package, please add these in the description field...

If there are no references, reply to the email explaining this. Consider adding a preemptive note in `cran-comments.md`:

```markdown

undefined

undefined

**DESCRIPTION Description:**
```r

**Function Documentation:**
```r

undefined