R Code

FetchRepoIssues <- function(
  strOwner = GetGHOwner(),   # length-1 character
  strRepo = GetGHRepo(),
  strGHToken = gh::gh_token(),
  strState = c("all", "open", "closed"),
  lglUpdate = FALSE,         # length-1 logical
  intPageMax = 100L,         # length-1 integer
  envCall = rlang::caller_env()
) { ... }

Files are named after the exported function they define: R/FetchRepoIssues.R for FetchRepoIssues().

General API design patterns

Enum-like arguments — declare choices as the default vector; resolve with rlang::arg_match() at the top of the function:

MyFunction <- function(x, mode = c("fast", "safe")) {
  mode <- rlang::arg_match(mode)
  # mode is now guaranteed to be "fast" or "safe"
}

NULL as "not provided" — use NULL as the default for optional arguments where there is no sensible scalar fallback; check with is.null():

MyFunction <- function(x, strNamesTo = NULL) {
  if (!is.null(strNamesTo)) { ... }
}

S3 object construction — build as a named list or tibble, set class explicitly with a dedicated constructor helper:

# Constructor assigns class
AsMyObject <- function(x) {
  class(x) <- c("qcthat_MyObject", class(x))
  x
}

envCall propagation in internal validators — helpers that validate arguments and may throw errors should accept and forward envCall:

CheckSomething <- function(x, envCall = rlang::caller_env()) {
  if (bad(x)) qcthatAbort("...", "bad_input", envCall = envCall)
}

MyExportedFn <- function(x, envCall = rlang::caller_env()) {
  CheckSomething(x, envCall)
}

Return tibbles, not plain data frames. Typed subclasses (e.g., qcthat_Issues) are tibbles with an additional class set by a constructor like AsIssuesDF().

Internal vs. exported functions

Export a function when:

• Users will call it directly
• Other packages may want to extend it
• It is a stable, intentional part of the API

Keep a function internal when:

• It is an implementation detail that may change
• It is only used within the package
• Exporting it would clutter the user-facing API

Internal helpers use PascalCase like exported ones, but with @keywords internal and no @export.

Error handling

Use qcthatAbort() (defined in R/aaa-conditions.R) rather than calling cli::cli_abort() directly. This ensures consistent error class formatting:

qcthatAbort(
  "Input {.arg strOwner} cannot be empty.",
  "bad_input",
  envCall = envCall
)

qcthatAbort() generates error classes of the form: qcthat-error-{subclass}, qcthat-error, qcthat-condition.

Always pass envCall = envCall (or envCall = rlang::caller_env()) so errors point to the user's call frame, not an internal helper.

Common package mistakes

# Never use library() inside package code
library(dplyr)          # Wrong