Document internal helpers and centralize shared internal params

.github/skills/document/SKILL.md

@@ -66,19 +66,19 @@ When a parameter takes one of a fixed set of values, document them with a bullet
 
 ## Returns
 
-Use `@returns` (not `@return`). Include a type when it's informative:
+Use `@returns` (not `@return`). Include a type or types:
 
 ```r
-#' @returns A summary tibble.
+#' @returns (`tibble`) A summary tibble.
 #' @returns (`logical(1)`) `TRUE` if `x` is a valid record.
-#' @returns Either a tibble or a list, depending on the input.
-#' @returns `NULL` (invisibly).
+#' @returns (`tibble` or `list`) Either a tibble or a list, depending on the input.
+#' @returns (`NULL`, invisibly) Called for warning side effect.
 ```
 
 **Structured returns with columns:**
 
 ```r
-#' @returns A [tibble::tibble()] with columns:
+#' @returns (`tibble`) A [tibble::tibble()] with columns:
 #'   - `name`: Record name.
 #'   - `value`: Numeric value.
 #'   - `status`: Status (`"active"` or `"inactive"`).
@@ -94,7 +94,7 @@ Use `@returns` (not `@return`). Include a type when it's informative:
 #' @param param_name (`TYPE`) Description.
 #' @inheritParams .shared-params
 #'
-#' @returns Description of return value.
+#' @returns (`TYPE`) Description of return value.
 #' @seealso [related_function()]
 #' @export
 #'
@@ -132,7 +132,7 @@ Use `@rdname` to group related functions under one help page. This applies to:
 #'
 #' @param x (`any`) The object to format.
 #' @param ... Additional arguments passed to methods.
-#' @returns A formatted character string.
+#' @returns (`character(1)`) A formatted summary string.
 #' @keywords internal
 .format_summary <- function(x, ...) {
   UseMethod(".format_summary")
@@ -152,7 +152,7 @@ Use `@rdname` to group related functions under one help page. This applies to:
 #'
 #' @param x (`TYPE`) Description.
 #' @param ... Additional arguments (ignored).
-#' @returns Description.
+#' @returns (`TYPE`) Description.
 #' @exportS3Method pkg::generic
 method.class <- function(x, ...) { ... }
 ```

R/aaa-conditions.R

@@ -2,7 +2,7 @@
 #'
 #' @inheritParams .shared-params
 #' @inheritParams stbl::pkg_abort
-#' @returns Does not return.
+#' @returns (`NULL`) Does not return.
 #' @keywords internal
 .pkg_abort <- function(
   message,
@@ -27,7 +27,7 @@
 #'
 #' @inheritParams .shared-params
 #' @inheritParams stbl::pkg_warn
-#' @returns `NULL`, invisibly (called for warning side effect).
+#' @returns (`NULL`, invisibly) Called for warning side effect.
 #' @keywords internal
 .pkg_warn <- function(
   message,
@@ -52,7 +52,7 @@
 #'
 #' @inheritParams .shared-params
 #' @inheritParams stbl::pkg_inform
-#' @returns `NULL`, invisibly (called for message side effect).
+#' @returns (`NULL`, invisibly) Called for message side effect.
 #' @keywords internal
 .pkg_inform <- function(
   message,

R/aaa-shared_params.R

@@ -3,20 +3,86 @@
 #' These parameters are used in multiple functions. They are defined here to
 #' make them easier to import and to find.
 #'
+#' @param addition (`character`) Text to append when `test` is `TRUE`.
+#' @param allow_empty (`logical`) Whether empty parameter values may be
+#'   represented as `NULL`.
 #' @param api_abbr (`character(1)`) A short (about 2-5 letter) abbreviation for
 #'   the API, for use in function names and environment variables.
 #' @param api_definition (`rapid::class_rapid`) The API definition to generate
 #'   package code from.
 #' @param api_title (`character(1)`) The API title used in generated package
 #'   files.
+#' @param base_path The root URL of the current project.
+#' @param base_url (`character(1)`) The base URL used in generated test
+#'   helpers.
 #' @param call (`environment`) The caller environment for error messages.
+#' @param config (`list`) Package-generation configuration data.
 #' @param config_file (`character(1)` or `fs_path`) The path to a beekeeper yaml
 #'   config file.
+#' @param data (`list`) Data passed to a template.
+#' @param dir (`character(1)`) The directory where a generated file should be
+#'   written.
+#' @param endpoint (`character(1)`) The operation endpoint.
+#' @param endpoints (`character`) Endpoint paths paired with operations.
+#' @param filter_in (`character(1)`) The parameter location to keep.
+#' @param include_stbl (`logical(1)`) Whether to add `stbl` to Imports.
+#' @param methods (`character`) HTTP methods paired with endpoints.
+#' @param operation (`character(1)`) The HTTP method.
+#' @param operation_description (`character(1)`) The operation description.
+#' @param operation_descriptions (`character`) Operation descriptions from the
+#'   API definition.
+#' @param operation_id (`character(1)`) The operation identifier used in
+#'   generated file names.
+#' @param operation_ids (`character`) Operation identifiers from the API
+#'   definition.
+#' @param operation_summaries (`character`) Operation summaries from the API
+#'   definition.
+#' @param operation_summary (`character(1)`) The operation summary.
+#' @param original (`character`) The original text.
+#' @param pagination_data (`list`) Pagination metadata used while generating
+#'   path files.
+#' @param parameters (`data.frame`) Operation parameters.
+#' @param params (`list`) Parameter metadata for a single operation.
+#' @param params_df (`data.frame`) Parameter metadata in tabular form.
+#' @param params_schema (`data.frame`) Schema metadata for operation parameters.
+#' @param path (`character(1)`) The path template.
+#' @param path_operation (`list`) Template data for one operation.
+#' @param paths (`rapid::class_paths`) API path definitions.
+#' @param paths_by_operation (`list`) Template-ready operations keyed by
+#'   operation identifier.
 #' @param pkg_dir (`character(1)` or `fs_path`) The directory containing package
 #'   files.
 #' @param rapid_file (`character(1)` or `fs_path`) The path to the R API
 #'   definition (rapid) file.
+#' @param required (`logical`) Whether each parameter is required.
+#' @param security_arg_description (`character(1)`) The argument description.
+#' @param security_arg_name (`character(1)`) The argument name.
+#' @param security_arg_names (`character`) Security argument names to exclude
+#'   from generated operation signatures (because they are defined once,
+#'   separately).
+#' @param security_args (`character`) Security argument names to remove from
+#'   operation parameters (because they are defined once, separately).
+#' @param security_data (`list`) Generated security metadata.
+#' @param security_scheme_collection (`list`) Collected security scheme
+#'   metadata.
+#' @param security_scheme_description (`character(1)`) A security scheme
+#'   description from the API definition.
+#' @param security_scheme_details (`rapid::class_security_scheme_details`) The
+#'   security scheme details.
+#' @param security_scheme_name (`character(1)`) The security scheme name.
+#' @param security_scheme_type (`character(1)`) The security scheme type.
+#' @param security_schemes (`rapid::class_security_schemes`) Security schemes
+#'   from the API definition.
+#' @param tag_operations (`list`) Operations grouped under one tag.
+#' @param tag_name (`character(1)`) The tag name.
+#' @param tags (`character` or `list`) Tags for all operations.
+#' @param target (`character(1)`) The name of the generated file.
+#' @param template (`character(1)`) The template file name to render.
+#' @param test (`logical`) A condition for each element of `original`.
 #' @param to_collapse (`character`) The character vector to collapse.
+#' @param type (`data.frame`) Joined parameter type metadata.
+#' @param x (`any`) The object to check or coerce.
+#' @param y (`any`) The default value.
 #'
 #' @name .shared-params
 #' @keywords internal

R/as_bk_data.R

@@ -2,14 +2,15 @@
 #'
 #' Convert `rapid` objects to lists of properties to use in beekeeper templates.
 #'
+#' @inheritParams .shared-params
 #' @inheritParams rlang::args_dots_empty
-#' @param x The object to coerce.
-#'
-#' @returns A list.
+#' @returns (`list`) A list.
 #' @keywords internal
 as_bk_data <- S7::new_generic("as_bk_data", dispatch_args = "x")
 
-S7::method(as_bk_data, class_any) <- function(x) {
+#' @rdname as_bk_data
+#' @keywords internal
+S7::method(as_bk_data, class_any) <- function(x, ...) {
   cli::cli_warn("No method for as_bk_data() for class {.cls {class(x)}}.")
   return(list())
 }

R/generate_pkg-pagination.R

@@ -1,3 +1,7 @@
+#' Generate pagination files
+#'
+#' @returns (`list`) Pagination metadata used while generating path files.
+#' @keywords internal
 .generate_pagination <- function() {
   # TODO: Accept pagination config and generate 030-pagination.R (#63)
   list()