From 0d26ded0d9a103f6c75ccc9127338f0efb803c3a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 16 May 2026 18:50:21 +0000 Subject: [PATCH 01/13] Initial plan From e32def99e5466cc10685871e1cc74346d80e2f38 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 16 May 2026 19:00:43 +0000 Subject: [PATCH 02/13] Document internal helper functions Agent-Logs-Url: https://github.com/api2r/beekeeper/sessions/fbf4f879-da36-4e65-975f-6ef573695aa6 Co-authored-by: jonthegeek <33983824+jonthegeek@users.noreply.github.com> --- R/aaa-shared_params.R | 33 ++++ R/as_bk_data.R | 2 + R/generate_pkg-pagination.R | 4 + R/generate_pkg-paths.R | 143 ++++++++++++++++++ R/generate_pkg-prepare.R | 15 ++ R/generate_pkg-security.R | 56 +++++++ R/generate_pkg-setup.R | 11 ++ R/generate_pkg-shared.R | 5 + R/generate_pkg-template.R | 5 + R/generate_pkg.R | 5 + R/use_beekeeper.R | 10 ++ R/utils.R | 45 +++++- R/zzz.R | 5 + man/as_bk_data.Rd | 23 ++- man/dot-bk_use_template_impl.Rd | 25 +++ man/dot-compile_param_class_descriptions.Rd | 23 +++ man/dot-describe_param_classes.Rd | 24 +++ man/dot-extract_params_by_location.Rd | 20 +++ man/dot-flatten_df_data_frame.Rd | 18 +++ man/dot-flatten_df_list.Rd | 18 +++ man/dot-flatten_df_null.Rd | 18 +++ man/dot-flatten_params_df.Rd | 18 +++ man/dot-generate_pagination.Rd | 15 ++ man/dot-generate_paths.Rd | 35 +++++ man/dot-generate_paths_file.Rd | 26 ++++ man/dot-generate_paths_files.Rd | 32 ++++ man/dot-generate_paths_test_file.Rd | 23 +++ man/dot-generate_pkg_impl.Rd | 23 +++ man/dot-generate_prepare.Rd | 23 +++ man/dot-generate_prepare_r.Rd | 23 +++ man/dot-generate_prepare_test.Rd | 19 +++ man/dot-generate_security.Rd | 22 +++ man/dot-generate_security_arg_help.Rd | 22 +++ man/dot-generate_security_signature.Rd | 22 +++ man/dot-generate_shared_params.Rd | 18 +++ man/dot-glue_pipe_brace.Rd | 20 +++ man/dot-onLoad.Rd | 18 +++ man/dot-param_schema_to_r.Rd | 19 +++ man/dot-params_to_args.Rd | 18 +++ man/dot-params_to_list.Rd | 18 +++ man/dot-params_to_named_args.Rd | 18 +++ man/dot-params_to_validations.Rd | 18 +++ man/dot-paste0_if.Rd | 22 +++ man/dot-path_as_arg.Rd | 20 +++ man/dot-path_row_to_list.Rd | 42 +++++ man/dot-paths_fill_descriptions.Rd | 22 +++ man/dot-paths_fill_operation_id.Rd | 23 +++ man/dot-paths_fill_summary.Rd | 23 +++ man/dot-paths_fill_tags.Rd | 18 +++ man/dot-paths_need_stbl.Rd | 21 +++ man/dot-paths_to_clean_df.Rd | 18 +++ man/dot-prep_param_args.Rd | 21 +++ man/dot-prepare_params_df.Rd | 18 +++ man/dot-remove_security_args.Rd | 21 +++ man/dot-security_arg_description_clean.Rd | 20 +++ man/dot-security_args_compile.Rd | 19 +++ ...dot-security_scheme_collection_finalize.Rd | 19 +++ man/dot-security_scheme_description_fill.Rd | 24 +++ man/dot-security_scheme_rotate.Rd | 28 ++++ man/dot-security_schemes_collect.Rd | 19 +++ man/dot-setup_r.Rd | 21 +++ man/dot-shared-params.Rd | 55 +++++++ man/dot-stabilize_config.Rd | 18 +++ man/dot-to_snake.Rd | 18 +++ man/dot-write_config.Rd | 28 ++++ man/dot-write_rapid.Rd | 22 +++ tests/testthat/test-documentation.R | 66 ++++++++ 67 files changed, 1580 insertions(+), 4 deletions(-) create mode 100644 man/dot-bk_use_template_impl.Rd create mode 100644 man/dot-compile_param_class_descriptions.Rd create mode 100644 man/dot-describe_param_classes.Rd create mode 100644 man/dot-extract_params_by_location.Rd create mode 100644 man/dot-flatten_df_data_frame.Rd create mode 100644 man/dot-flatten_df_list.Rd create mode 100644 man/dot-flatten_df_null.Rd create mode 100644 man/dot-flatten_params_df.Rd create mode 100644 man/dot-generate_pagination.Rd create mode 100644 man/dot-generate_paths.Rd create mode 100644 man/dot-generate_paths_file.Rd create mode 100644 man/dot-generate_paths_files.Rd create mode 100644 man/dot-generate_paths_test_file.Rd create mode 100644 man/dot-generate_pkg_impl.Rd create mode 100644 man/dot-generate_prepare.Rd create mode 100644 man/dot-generate_prepare_r.Rd create mode 100644 man/dot-generate_prepare_test.Rd create mode 100644 man/dot-generate_security.Rd create mode 100644 man/dot-generate_security_arg_help.Rd create mode 100644 man/dot-generate_security_signature.Rd create mode 100644 man/dot-generate_shared_params.Rd create mode 100644 man/dot-glue_pipe_brace.Rd create mode 100644 man/dot-onLoad.Rd create mode 100644 man/dot-param_schema_to_r.Rd create mode 100644 man/dot-params_to_args.Rd create mode 100644 man/dot-params_to_list.Rd create mode 100644 man/dot-params_to_named_args.Rd create mode 100644 man/dot-params_to_validations.Rd create mode 100644 man/dot-paste0_if.Rd create mode 100644 man/dot-path_as_arg.Rd create mode 100644 man/dot-path_row_to_list.Rd create mode 100644 man/dot-paths_fill_descriptions.Rd create mode 100644 man/dot-paths_fill_operation_id.Rd create mode 100644 man/dot-paths_fill_summary.Rd create mode 100644 man/dot-paths_fill_tags.Rd create mode 100644 man/dot-paths_need_stbl.Rd create mode 100644 man/dot-paths_to_clean_df.Rd create mode 100644 man/dot-prep_param_args.Rd create mode 100644 man/dot-prepare_params_df.Rd create mode 100644 man/dot-remove_security_args.Rd create mode 100644 man/dot-security_arg_description_clean.Rd create mode 100644 man/dot-security_args_compile.Rd create mode 100644 man/dot-security_scheme_collection_finalize.Rd create mode 100644 man/dot-security_scheme_description_fill.Rd create mode 100644 man/dot-security_scheme_rotate.Rd create mode 100644 man/dot-security_schemes_collect.Rd create mode 100644 man/dot-setup_r.Rd create mode 100644 man/dot-stabilize_config.Rd create mode 100644 man/dot-to_snake.Rd create mode 100644 man/dot-write_config.Rd create mode 100644 man/dot-write_rapid.Rd create mode 100644 tests/testthat/test-documentation.R diff --git a/R/aaa-shared_params.R b/R/aaa-shared_params.R index 0ea641a..753469d 100644 --- a/R/aaa-shared_params.R +++ b/R/aaa-shared_params.R @@ -3,6 +3,8 @@ #' These parameters are used in multiple functions. They are defined here to #' make them easier to import and to find. #' +#' @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 @@ -10,12 +12,43 @@ #' @param api_title (`character(1)`) The API title used in generated package #' files. #' @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 endpoints (`character`) Endpoint paths paired with operations. +#' @param methods (`character`) HTTP methods paired with endpoints. +#' @param operation_id (`character(1)`) The operation identifier used in +#' generated file names. +#' @param operation_summaries (`character`) Operation summaries from the API +#' definition. +#' @param pagination_data (`list`) Pagination metadata used while generating +#' path files. +#' @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 paths (`rapid::class_paths`) API path definitions. #' @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_names (`character`) Security argument names to exclude +#' from generated operation signatures. +#' @param security_args (`character`) Security argument names to remove from +#' operation parameters. +#' @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_schemes (`rapid::class_security_schemes`) Security schemes +#' from the API definition. +#' @param target (`character(1)`) The name of the generated file. +#' @param template (`character(1)`) The template file name to render. #' @param to_collapse (`character`) The character vector to collapse. #' #' @name .shared-params diff --git a/R/as_bk_data.R b/R/as_bk_data.R index 44a10d2..2df1bdd 100644 --- a/R/as_bk_data.R +++ b/R/as_bk_data.R @@ -9,6 +9,8 @@ #' @keywords internal as_bk_data <- S7::new_generic("as_bk_data", dispatch_args = "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()) diff --git a/R/generate_pkg-pagination.R b/R/generate_pkg-pagination.R index 8e70eaa..527531b 100644 --- a/R/generate_pkg-pagination.R +++ b/R/generate_pkg-pagination.R @@ -1,3 +1,7 @@ +#' Generate pagination files +#' +#' @returns An empty `list`. +#' @keywords internal .generate_pagination <- function() { # TODO: Accept pagination config and generate 030-pagination.R (#63) list() diff --git a/R/generate_pkg-paths.R b/R/generate_pkg-paths.R index 8f816dc..22aa1aa 100644 --- a/R/generate_pkg-paths.R +++ b/R/generate_pkg-paths.R @@ -1,3 +1,10 @@ +#' Generate files for API paths +#' +#' @param base_url (`character(1)`) The base URL used in generated test +#' helpers. +#' @inheritParams .shared-params +#' @returns A `character` vector of generated file paths. +#' @keywords internal .generate_paths <- function( paths, api_abbr, @@ -26,6 +33,8 @@ # reshape data ----------------------------------------------------------------- +#' @rdname as_bk_data +#' @keywords internal S7::method(as_bk_data, class_paths) <- function(x) { if (!length(x)) { return(list()) @@ -36,6 +45,11 @@ S7::method(as_bk_data, class_paths) <- function(x) { result } +#' Convert API paths to an operations data frame +#' +#' @inheritParams .shared-params +#' @returns A [tibble::tibble()] with one row per non-deprecated operation. +#' @keywords internal .paths_to_clean_df <- function(paths) { operations_df <- tibble::as_tibble(paths) |> tidyr::unnest("operations") @@ -70,22 +84,46 @@ S7::method(as_bk_data, class_paths) <- function(x) { ### fill data ------------------------------------------------------------------ +#' Fill missing operation tags +#' +#' @param tags (`list`) Operation tags from the API definition. +#' @returns (`character`) Snake-case tag names. +#' @keywords internal .paths_fill_tags <- function(tags) { tags[lengths(tags) == 0] <- "general" tags <- purrr::map_chr(tags, 1) return(.to_snake(tags)) } +#' Fill missing operation identifiers +#' +#' @param operation_ids (`character`) Operation identifiers from the API +#' definition. +#' @inheritParams .shared-params +#' @returns (`character`) Operation identifiers. +#' @keywords internal .paths_fill_operation_id <- function(operation_ids, endpoints, methods) { .to_snake(operation_ids) %|% glue::glue("{methods}_{.to_snake(endpoints)}") } +#' Fill missing operation summaries +#' +#' @inheritParams .shared-params +#' @returns (`character`) Human-readable operation summaries. +#' @keywords internal .paths_fill_summary <- function(operation_summaries, endpoints, methods) { endpoints_spaced <- stringr::str_replace_all(.to_snake(endpoints), "_", " ") stringr::str_squish(operation_summaries) %|% stringr::str_to_sentence(glue::glue("{methods} {endpoints_spaced}")) } +#' Fill missing operation descriptions +#' +#' @param operation_descriptions (`character`) Operation descriptions from the +#' API definition. +#' @inheritParams .shared-params +#' @returns (`character`) Operation descriptions. +#' @keywords internal .paths_fill_descriptions <- function( operation_descriptions, operation_summaries @@ -101,6 +139,18 @@ S7::method(as_bk_data, class_paths) <- function(x) { ### create template data ------------------------------------------------------- +#' Convert one operation row to template data +#' +#' @param endpoint (`character(1)`) The operation endpoint. +#' @param operation (`character(1)`) The HTTP method. +#' @param operation_summary (`character(1)`) The operation summary. +#' @param operation_description (`character(1)`) The operation description. +#' @param tags (`character(1)`) The operation tag. +#' @param parameters (`data.frame`) Operation parameters. +#' @param ... Additional columns, ignored. +#' @inheritParams .shared-params +#' @returns A `list` describing one operation. +#' @keywords internal .path_row_to_list <- function( operation_id, endpoint, @@ -125,6 +175,11 @@ S7::method(as_bk_data, class_paths) <- function(x) { ) } +#' Prepare parameter metadata +#' +#' @inheritParams .shared-params +#' @returns A `data.frame` of prepared parameter metadata. +#' @keywords internal .prepare_params_df <- function(params_df) { params_df <- .flatten_params_df(params_df) if (nrow(params_df)) { @@ -144,6 +199,11 @@ S7::method(as_bk_data, class_paths) <- function(x) { return(params_df) } +#' Flatten parameter metadata +#' +#' @inheritParams .shared-params +#' @returns A `data.frame` of flattened parameter metadata. +#' @keywords internal .flatten_params_df <- function(params_df) { params_df <- .flatten_df(params_df) if (nrow(params_df)) { @@ -152,6 +212,11 @@ S7::method(as_bk_data, class_paths) <- function(x) { return(params_df) } +#' Convert parameter rows to a list +#' +#' @inheritParams .shared-params +#' @returns A `list` of parameter metadata entries. +#' @keywords internal .params_to_list <- function(params_df) { if (!nrow(params_df)) { return(list()) @@ -169,6 +234,12 @@ S7::method(as_bk_data, class_paths) <- function(x) { ) } +#' Extract parameter names by location +#' +#' @param filter_in (`character(1)`) The parameter location to keep. +#' @inheritParams .shared-params +#' @returns (`character`) Parameter names for the requested location. +#' @keywords internal .extract_params_by_location <- function(params_df, filter_in) { if (!nrow(params_df)) { return(character()) @@ -176,6 +247,11 @@ S7::method(as_bk_data, class_paths) <- function(x) { return(params_df$name[params_df$`in` == filter_in]) } +#' Describe parameter classes +#' +#' @inheritParams .shared-params +#' @returns (`character`) Display strings for parameter classes. +#' @keywords internal .describe_param_classes <- function(params_schema, allow_empty, required) { # TODO: Use enum and/or description when available. # @@ -197,6 +273,11 @@ S7::method(as_bk_data, class_paths) <- function(x) { return(.compile_param_class_descriptions(type, allow_empty, required)) } +#' Map parameter schemas to `stbl` helpers +#' +#' @inheritParams .shared-params +#' @returns (`character`) Coercion helper names. +#' @keywords internal .param_schema_to_r <- function(params_schema) { type <- dplyr::left_join( dplyr::select(params_schema, "type", "format"), @@ -206,6 +287,12 @@ S7::method(as_bk_data, class_paths) <- function(x) { type$to_r } +#' Compile parameter class descriptions +#' +#' @param type (`data.frame`) Joined parameter type metadata. +#' @inheritParams .shared-params +#' @returns (`character`) Parameter class descriptions. +#' @keywords internal .compile_param_class_descriptions <- function(type, allow_empty, required) { r_class_descriptions <- glue::glue("length-1 `{type$r_class_name}`") |> .paste0_if( @@ -220,6 +307,12 @@ S7::method(as_bk_data, class_paths) <- function(x) { return(r_class_descriptions) } +#' Convert a path to a request argument +#' +#' @param path (`character(1)`) The path template. +#' @inheritParams .shared-params +#' @returns (`character(1)`) Code for the request path argument. +#' @keywords internal .path_as_arg <- function(path, params_df) { if (!nrow(params_df) || !any(params_df$`in` == "path")) { return(glue::glue('"{path}"')) @@ -231,6 +324,13 @@ S7::method(as_bk_data, class_paths) <- function(x) { # generate files --------------------------------------------------------------- +#' Generate files for all operations +#' +#' @param paths_by_operation (`list`) Template-ready operations keyed by +#' operation identifier. +#' @inheritParams .shared-params +#' @returns A `character` vector of generated file paths. +#' @keywords internal .generate_paths_files <- function( paths_by_operation, api_abbr, @@ -280,14 +380,29 @@ S7::method(as_bk_data, class_paths) <- function(x) { return(c(r_files, test_files)) } +#' Convert parameters to a signature string +#' +#' @inheritParams .shared-params +#' @returns (`character(1)`) A comma-separated parameter string. +#' @keywords internal .params_to_args <- function(params) { .collapse_comma(purrr::map_chr(params, "name")) %|a|% character() } +#' Convert parameters to named arguments +#' +#' @inheritParams .shared-params +#' @returns (`character(1)`) A comma-separated named-argument string. +#' @keywords internal .params_to_named_args <- function(params) { .collapse_comma_self_equal(purrr::map_chr(params, "name")) %|a|% character() } +#' Remove security parameters +#' +#' @inheritParams .shared-params +#' @returns A `list` of non-security parameters. +#' @keywords internal .remove_security_args <- function(params, security_args) { purrr::discard( params, @@ -297,10 +412,20 @@ S7::method(as_bk_data, class_paths) <- function(x) { ) } +#' Prepare parameter arguments +#' +#' @inheritParams .shared-params +#' @returns (`character(1)`) A comma-separated named-argument string. +#' @keywords internal .prep_param_args <- function(params, security_args) { .collapse_comma_self_equal(setdiff(params, security_args)) %|a|% character() } +#' Convert parameters to validation metadata +#' +#' @inheritParams .shared-params +#' @returns A `list` of validation metadata. +#' @keywords internal .params_to_validations <- function(params) { checks <- purrr::keep( params, @@ -318,6 +443,11 @@ S7::method(as_bk_data, class_paths) <- function(x) { ) } +#' Determine whether generated paths need `stbl` +#' +#' @inheritParams .shared-params +#' @returns (`logical(1)`) `TRUE` if any path needs `stbl`. +#' @keywords internal .paths_need_stbl <- function(paths, security_arg_names = character()) { ops <- as_bk_data(paths) if (!length(ops)) { @@ -329,6 +459,12 @@ S7::method(as_bk_data, class_paths) <- function(x) { })) } +#' Generate one operation file +#' +#' @param path_operation (`list`) Template data for one operation. +#' @inheritParams .shared-params +#' @returns (`character(1)`) The generated file path. +#' @keywords internal .generate_paths_file <- function( path_operation, operation_id, @@ -352,6 +488,13 @@ S7::method(as_bk_data, class_paths) <- function(x) { ) } +#' Generate one tag-level test file +#' +#' @param tag_operations (`list`) Operations grouped under one tag. +#' @param tag_name (`character(1)`) The tag name. +#' @inheritParams .shared-params +#' @returns (`character(1)`) The generated test file path. +#' @keywords internal .generate_paths_test_file <- function(tag_operations, tag_name, api_abbr) { paths_list <- unname(purrr::imap(tag_operations, function(op, op_id) { list( diff --git a/R/generate_pkg-prepare.R b/R/generate_pkg-prepare.R index 8ad4e80..7ed1068 100644 --- a/R/generate_pkg-prepare.R +++ b/R/generate_pkg-prepare.R @@ -1,3 +1,8 @@ +#' Generate prepare files +#' +#' @inheritParams .shared-params +#' @returns A `character` vector of generated file paths. +#' @keywords internal .generate_prepare <- function(config, api_definition, security_data) { c( .generate_prepare_r(config, api_definition, security_data), @@ -5,6 +10,11 @@ ) } +#' Generate the prepare helper +#' +#' @inheritParams .shared-params +#' @returns (`character(1)`) The generated file path. +#' @keywords internal .generate_prepare_r <- function(config, api_definition, security_data) { .bk_use_template( template = "010-prepare.R", @@ -20,6 +30,11 @@ ) } +#' Generate prepare tests +#' +#' @inheritParams .shared-params +#' @returns (`character(1)`) The generated test file path. +#' @keywords internal .generate_prepare_test <- function(api_abbr) { .bk_use_template( template = "test-010-prepare.R", diff --git a/R/generate_pkg-security.R b/R/generate_pkg-security.R index 6c960f7..c8473eb 100644 --- a/R/generate_pkg-security.R +++ b/R/generate_pkg-security.R @@ -1,3 +1,8 @@ +#' Generate security files and metadata +#' +#' @inheritParams .shared-params +#' @returns A `list` of generated security metadata. +#' @keywords internal .generate_security <- function(api_abbr, security_schemes) { security_data <- as_bk_data(security_schemes) if (length(security_data)) { @@ -13,6 +18,11 @@ return(security_data) } +#' Generate a security argument signature +#' +#' @inheritParams .shared-params +#' @returns (`character(1)`) A function-signature fragment. +#' @keywords internal .generate_security_signature <- function(security_arg_names, api_abbr) { env_vars <- toupper(glue::glue("{api_abbr}_{security_arg_names}")) return( @@ -22,6 +32,8 @@ ) } +#' @rdname as_bk_data +#' @keywords internal S7::method(as_bk_data, class_security_schemes) <- function(x) { if (!length(x)) { return(list()) @@ -30,6 +42,11 @@ S7::method(as_bk_data, class_security_schemes) <- function(x) { return(.security_scheme_collection_finalize(security_scheme_collection)) } +#' Collect security scheme metadata +#' +#' @inheritParams .shared-params +#' @returns A `list` of security scheme metadata. +#' @keywords internal .security_schemes_collect <- function(security_schemes) { purrr::pmap( list( @@ -42,6 +59,14 @@ S7::method(as_bk_data, class_security_schemes) <- function(x) { ) } +#' Convert one security scheme to a list +#' +#' @param security_scheme_name (`character(1)`) The security scheme name. +#' @param security_scheme_details (`rapid::class_security_scheme_details`) The +#' security scheme details. +#' @inheritParams .shared-params +#' @returns A `list` describing one security scheme. +#' @keywords internal .security_scheme_rotate <- function( security_scheme_name, security_scheme_details, @@ -61,6 +86,12 @@ S7::method(as_bk_data, class_security_schemes) <- function(x) { return(security_scheme_list) } +#' Fill a missing security scheme description +#' +#' @param security_scheme_type (`character(1)`) The security scheme type. +#' @inheritParams .shared-params +#' @returns (`character(1)`) A security scheme description. +#' @keywords internal .security_scheme_description_fill <- function( security_scheme_description, security_scheme_type @@ -83,6 +114,11 @@ S7::method(as_bk_data, class_security_schemes) <- function(x) { "Check the API documentation for details." ) +#' Finalize collected security scheme data +#' +#' @inheritParams .shared-params +#' @returns A `list` of finalized security metadata. +#' @keywords internal .security_scheme_collection_finalize <- function(security_scheme_collection) { security_scheme_data <- c( list( @@ -94,6 +130,11 @@ S7::method(as_bk_data, class_security_schemes) <- function(x) { return(security_scheme_data) } +#' Compile security argument metadata +#' +#' @inheritParams .shared-params +#' @returns A `list` of compiled security argument values. +#' @keywords internal .security_args_compile <- function(security_scheme_collection) { security_args <- sort(unique(purrr::map_chr( security_scheme_collection, @@ -112,6 +153,11 @@ S7::method(as_bk_data, class_security_schemes) <- function(x) { )) } +#' Build security argument help entries +#' +#' @inheritParams .shared-params +#' @returns A `list` of template-ready parameter help entries. +#' @keywords internal .generate_security_arg_help <- function( security_scheme_collection, security_args @@ -130,6 +176,12 @@ S7::method(as_bk_data, class_security_schemes) <- function(x) { ) } +#' Format one security argument help entry +#' +#' @param security_arg_description (`character(1)`) The argument description. +#' @param security_arg_name (`character(1)`) The argument name. +#' @returns A named `list` with `name` and `description`. +#' @keywords internal .security_arg_description_clean <- function( security_arg_description, security_arg_name @@ -137,10 +189,14 @@ S7::method(as_bk_data, class_security_schemes) <- function(x) { list(name = security_arg_name, description = security_arg_description) } +#' @rdname as_bk_data +#' @keywords internal S7::method(as_bk_data, class_security_scheme_details) <- function(x) { purrr::map(x, as_bk_data) } +#' @rdname as_bk_data +#' @keywords internal S7::method(as_bk_data, class_api_key_security_scheme) <- function(x) { if (length(x)) { return( diff --git a/R/generate_pkg-setup.R b/R/generate_pkg-setup.R index e5a4eee..ed312f3 100644 --- a/R/generate_pkg-setup.R +++ b/R/generate_pkg-setup.R @@ -59,6 +59,11 @@ read_config <- function(pkg_dir = ".", config_file = "_beekeeper.yml") { return(.stabilize_config(config)) } +#' Stabilize beekeeper config values +#' +#' @inheritParams .shared-params +#' @returns A stabilized `list`. +#' @keywords internal .stabilize_config <- function(config) { config$api_title <- stbl::stabilize_character_scalar(config$api_title) config$api_abbr <- stbl::stabilize_character_scalar(config$api_abbr) @@ -92,6 +97,12 @@ read_api_definition <- function( readRDS(fs::path(pkg_dir, rapid_file)) } +#' Set up package directories and dependencies +#' +#' @param include_stbl (`logical(1)`) Whether to add `stbl` to Imports. +#' @inheritParams .shared-params +#' @returns `NULL` (invisibly). +#' @keywords internal .setup_r <- function(pkg_dir, include_stbl = FALSE) { if (as.character(pkg_dir) != ".") { usethis::local_project(pkg_dir, quiet = TRUE) # nocov diff --git a/R/generate_pkg-shared.R b/R/generate_pkg-shared.R index 7564df1..6d89be2 100644 --- a/R/generate_pkg-shared.R +++ b/R/generate_pkg-shared.R @@ -1,3 +1,8 @@ +#' Generate shared parameter docs +#' +#' @inheritParams .shared-params +#' @returns (`character(1)`) The generated file path. +#' @keywords internal .generate_shared_params <- function(security_data) { shared_file_path <- .bk_use_template( template = "000-shared.R", diff --git a/R/generate_pkg-template.R b/R/generate_pkg-template.R index 023e557..1cf1677 100644 --- a/R/generate_pkg-template.R +++ b/R/generate_pkg-template.R @@ -21,6 +21,11 @@ return(invisible(target)) } +#' Write a rendered template to disk +#' +#' @inheritParams .shared-params +#' @returns (`character(1)`) The generated file path. +#' @keywords internal .bk_use_template_impl <- function(template, data, target, dir) { target <- usethis::proj_path(dir, target) save_as <- fs::path_rel(target, usethis::proj_path()) diff --git a/R/generate_pkg.R b/R/generate_pkg.R index e32a680..9654c24 100644 --- a/R/generate_pkg.R +++ b/R/generate_pkg.R @@ -41,6 +41,11 @@ generate_pkg <- function( return(invisible(touched_files)) } +#' Generate package files from prepared inputs +#' +#' @inheritParams .shared-params +#' @returns A `character` vector of generated file paths, invisibly. +#' @keywords internal .generate_pkg_impl <- function(config, api_definition, security_data) { prep_files <- .generate_prepare(config, api_definition, security_data) pagination_data <- .generate_pagination() diff --git a/R/use_beekeeper.R b/R/use_beekeeper.R index ea8cdde..27ab82f 100644 --- a/R/use_beekeeper.R +++ b/R/use_beekeeper.R @@ -34,6 +34,11 @@ use_beekeeper <- function( return(invisible(config_file)) } +#' Write the rapid definition file +#' +#' @inheritParams .shared-params +#' @returns (`character(1)`) The written file path. +#' @keywords internal .write_rapid <- function(api_definition, rapid_file) { rapid_file <- stbl::stabilize_character_scalar(rapid_file) saveRDS(api_definition, rapid_file) @@ -41,6 +46,11 @@ use_beekeeper <- function( return(rapid_file) } +#' Write the beekeeper config file +#' +#' @inheritParams .shared-params +#' @returns (`character(1)`) The written config file path. +#' @keywords internal .write_config <- function(api_definition, api_abbr, rapid_file, config_file) { config_file <- stbl::stabilize_character_scalar(config_file) update_time <- strptime(Sys.time(), format = "%Y-%m-%d %H:%M:%S", tz = "UTC") diff --git a/R/utils.R b/R/utils.R index 9f44022..a17f107 100644 --- a/R/utils.R +++ b/R/utils.R @@ -108,14 +108,32 @@ if (exists("%||%", envir = baseenv())) { .collapse_comma(glue::glue("{x} = {x}")) } +#' Append text conditionally +#' +#' @param original (`character`) The original text. +#' @param test (`logical`) A condition for each element of `original`. +#' @param addition (`character`) Text to append when `test` is `TRUE`. +#' @returns (`character`) The updated text. +#' @keywords internal .paste0_if <- function(original, test, addition) { ifelse(test, paste0(original, addition), original) } +#' Interpolate glue with pipe braces +#' +#' @param ... Expressions passed to [glue::glue()]. +#' @param .envir (`environment`) The environment in which to evaluate `...`. +#' @returns A glue object. +#' @keywords internal .glue_pipe_brace <- function(..., .envir = rlang::caller_env()) { glue::glue(..., .open = "|{", .close = "}|", .envir = .envir) } +#' Convert text to snake case +#' +#' @param x (`character`) Text to convert. +#' @returns (`character`) Snake-case text. +#' @keywords internal .to_snake <- function(x) { snakecase::to_snake_case(x, parsing_option = 3) } @@ -129,8 +147,29 @@ if (exists("%||%", envir = baseenv())) { #' @keywords internal .flatten_df <- S7::new_generic(".flatten_df", dispatch_args = "x") -S7::method(.flatten_df, class_data.frame) <- function(x) x +#' Flatten a data frame method +#' +#' @param x (`data.frame`) The object to return unchanged. +#' @returns A `data.frame`. +#' @keywords internal +.flatten_df_data_frame <- function(x) x -S7::method(.flatten_df, class_list) <- function(x) purrr::list_rbind(x) +S7::method(.flatten_df, class_data.frame) <- .flatten_df_data_frame + +#' Flatten a list method +#' +#' @param x (`list`) The objects to row-bind. +#' @returns A `data.frame`. +#' @keywords internal +.flatten_df_list <- function(x) purrr::list_rbind(x) + +S7::method(.flatten_df, class_list) <- .flatten_df_list + +#' Flatten a `NULL` method +#' +#' @param x (`NULL`) The object to convert. +#' @returns A `data.frame`. +#' @keywords internal +.flatten_df_null <- function(x) data.frame() -S7::method(.flatten_df, NULL) <- function(x) data.frame() +S7::method(.flatten_df, NULL) <- .flatten_df_null diff --git a/R/zzz.R b/R/zzz.R index 0b7eb0c..cf702e7 100644 --- a/R/zzz.R +++ b/R/zzz.R @@ -1,3 +1,8 @@ +#' Register package methods on load +#' +#' @param ... Additional arguments passed by R during package loading. +#' @returns `NULL` (invisibly). +#' @keywords internal .onLoad <- function(...) { S7::methods_register() # nocov } diff --git a/man/as_bk_data.Rd b/man/as_bk_data.Rd index 17a1d1c..e5b8a00 100644 --- a/man/as_bk_data.Rd +++ b/man/as_bk_data.Rd @@ -1,10 +1,31 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/as_bk_data.R +% Please edit documentation in R/as_bk_data.R, R/generate_pkg-paths.R, +% R/generate_pkg-security.R \name{as_bk_data} \alias{as_bk_data} +\alias{as_bk_data,any-method} +\alias{as_bk_data,rapid::paths-method} +\alias{as_bk_data,rapid::security_schemes-method} +\alias{as_bk_data,rapid::security_scheme_details-method} +\alias{as_bk_data,rapid::api_key_security_scheme-method} \title{Prepare rapid objects for beekeeper} \usage{ as_bk_data(x, ...) + +## S7 method for class +as_bk_data(x) + +## S7 method for class +as_bk_data(x) + +## S7 method for class +as_bk_data(x) + +## S7 method for class +as_bk_data(x) + +## S7 method for class +as_bk_data(x) } \arguments{ \item{x}{The object to coerce.} diff --git a/man/dot-bk_use_template_impl.Rd b/man/dot-bk_use_template_impl.Rd new file mode 100644 index 0000000..4263323 --- /dev/null +++ b/man/dot-bk_use_template_impl.Rd @@ -0,0 +1,25 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-template.R +\name{.bk_use_template_impl} +\alias{.bk_use_template_impl} +\title{Write a rendered template to disk} +\usage{ +.bk_use_template_impl(template, data, target, dir) +} +\arguments{ +\item{template}{(\code{character(1)}) The template file name to render.} + +\item{data}{(\code{list}) Data passed to a template.} + +\item{target}{(\code{character(1)}) The name of the generated file.} + +\item{dir}{(\code{character(1)}) The directory where a generated file should be +written.} +} +\value{ +(\code{character(1)}) The generated file path. +} +\description{ +Write a rendered template to disk +} +\keyword{internal} diff --git a/man/dot-compile_param_class_descriptions.Rd b/man/dot-compile_param_class_descriptions.Rd new file mode 100644 index 0000000..cc3a760 --- /dev/null +++ b/man/dot-compile_param_class_descriptions.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.compile_param_class_descriptions} +\alias{.compile_param_class_descriptions} +\title{Compile parameter class descriptions} +\usage{ +.compile_param_class_descriptions(type, allow_empty, required) +} +\arguments{ +\item{type}{(\code{data.frame}) Joined parameter type metadata.} + +\item{allow_empty}{(\code{logical}) Whether empty parameter values may be +represented as \code{NULL}.} + +\item{required}{(\code{logical}) Whether each parameter is required.} +} +\value{ +(\code{character}) Parameter class descriptions. +} +\description{ +Compile parameter class descriptions +} +\keyword{internal} diff --git a/man/dot-describe_param_classes.Rd b/man/dot-describe_param_classes.Rd new file mode 100644 index 0000000..c89a275 --- /dev/null +++ b/man/dot-describe_param_classes.Rd @@ -0,0 +1,24 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.describe_param_classes} +\alias{.describe_param_classes} +\title{Describe parameter classes} +\usage{ +.describe_param_classes(params_schema, allow_empty, required) +} +\arguments{ +\item{params_schema}{(\code{data.frame}) Schema metadata for operation +parameters.} + +\item{allow_empty}{(\code{logical}) Whether empty parameter values may be +represented as \code{NULL}.} + +\item{required}{(\code{logical}) Whether each parameter is required.} +} +\value{ +(\code{character}) Display strings for parameter classes. +} +\description{ +Describe parameter classes +} +\keyword{internal} diff --git a/man/dot-extract_params_by_location.Rd b/man/dot-extract_params_by_location.Rd new file mode 100644 index 0000000..ae912a3 --- /dev/null +++ b/man/dot-extract_params_by_location.Rd @@ -0,0 +1,20 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.extract_params_by_location} +\alias{.extract_params_by_location} +\title{Extract parameter names by location} +\usage{ +.extract_params_by_location(params_df, filter_in) +} +\arguments{ +\item{params_df}{(\code{data.frame}) Parameter metadata in tabular form.} + +\item{filter_in}{(\code{character(1)}) The parameter location to keep.} +} +\value{ +(\code{character}) Parameter names for the requested location. +} +\description{ +Extract parameter names by location +} +\keyword{internal} diff --git a/man/dot-flatten_df_data_frame.Rd b/man/dot-flatten_df_data_frame.Rd new file mode 100644 index 0000000..d043df4 --- /dev/null +++ b/man/dot-flatten_df_data_frame.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/utils.R +\name{.flatten_df_data_frame} +\alias{.flatten_df_data_frame} +\title{Flatten a data frame method} +\usage{ +.flatten_df_data_frame(x) +} +\arguments{ +\item{x}{(\code{data.frame}) The object to return unchanged.} +} +\value{ +A \code{data.frame}. +} +\description{ +Flatten a data frame method +} +\keyword{internal} diff --git a/man/dot-flatten_df_list.Rd b/man/dot-flatten_df_list.Rd new file mode 100644 index 0000000..588c74b --- /dev/null +++ b/man/dot-flatten_df_list.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/utils.R +\name{.flatten_df_list} +\alias{.flatten_df_list} +\title{Flatten a list method} +\usage{ +.flatten_df_list(x) +} +\arguments{ +\item{x}{(\code{list}) The objects to row-bind.} +} +\value{ +A \code{data.frame}. +} +\description{ +Flatten a list method +} +\keyword{internal} diff --git a/man/dot-flatten_df_null.Rd b/man/dot-flatten_df_null.Rd new file mode 100644 index 0000000..3fec3b5 --- /dev/null +++ b/man/dot-flatten_df_null.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/utils.R +\name{.flatten_df_null} +\alias{.flatten_df_null} +\title{Flatten a \code{NULL} method} +\usage{ +.flatten_df_null(x) +} +\arguments{ +\item{x}{(\code{NULL}) The object to convert.} +} +\value{ +A \code{data.frame}. +} +\description{ +Flatten a \code{NULL} method +} +\keyword{internal} diff --git a/man/dot-flatten_params_df.Rd b/man/dot-flatten_params_df.Rd new file mode 100644 index 0000000..65e32e1 --- /dev/null +++ b/man/dot-flatten_params_df.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.flatten_params_df} +\alias{.flatten_params_df} +\title{Flatten parameter metadata} +\usage{ +.flatten_params_df(params_df) +} +\arguments{ +\item{params_df}{(\code{data.frame}) Parameter metadata in tabular form.} +} +\value{ +A \code{data.frame} of flattened parameter metadata. +} +\description{ +Flatten parameter metadata +} +\keyword{internal} diff --git a/man/dot-generate_pagination.Rd b/man/dot-generate_pagination.Rd new file mode 100644 index 0000000..e61234a --- /dev/null +++ b/man/dot-generate_pagination.Rd @@ -0,0 +1,15 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-pagination.R +\name{.generate_pagination} +\alias{.generate_pagination} +\title{Generate pagination files} +\usage{ +.generate_pagination() +} +\value{ +An empty \code{list}. +} +\description{ +Generate pagination files +} +\keyword{internal} diff --git a/man/dot-generate_paths.Rd b/man/dot-generate_paths.Rd new file mode 100644 index 0000000..64dcad7 --- /dev/null +++ b/man/dot-generate_paths.Rd @@ -0,0 +1,35 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.generate_paths} +\alias{.generate_paths} +\title{Generate files for API paths} +\usage{ +.generate_paths( + paths, + api_abbr, + security_data, + pagination_data = list(), + base_url +) +} +\arguments{ +\item{paths}{(\code{rapid::class_paths}) API path definitions.} + +\item{api_abbr}{(\code{character(1)}) A short (about 2-5 letter) abbreviation for +the API, for use in function names and environment variables.} + +\item{security_data}{(\code{list}) Generated security metadata.} + +\item{pagination_data}{(\code{list}) Pagination metadata used while generating +path files.} + +\item{base_url}{(\code{character(1)}) The base URL used in generated test +helpers.} +} +\value{ +A \code{character} vector of generated file paths. +} +\description{ +Generate files for API paths +} +\keyword{internal} diff --git a/man/dot-generate_paths_file.Rd b/man/dot-generate_paths_file.Rd new file mode 100644 index 0000000..d137dad --- /dev/null +++ b/man/dot-generate_paths_file.Rd @@ -0,0 +1,26 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.generate_paths_file} +\alias{.generate_paths_file} +\title{Generate one operation file} +\usage{ +.generate_paths_file(path_operation, operation_id, api_abbr, security_data) +} +\arguments{ +\item{path_operation}{(\code{list}) Template data for one operation.} + +\item{operation_id}{(\code{character(1)}) The operation identifier used in +generated file names.} + +\item{api_abbr}{(\code{character(1)}) A short (about 2-5 letter) abbreviation for +the API, for use in function names and environment variables.} + +\item{security_data}{(\code{list}) Generated security metadata.} +} +\value{ +(\code{character(1)}) The generated file path. +} +\description{ +Generate one operation file +} +\keyword{internal} diff --git a/man/dot-generate_paths_files.Rd b/man/dot-generate_paths_files.Rd new file mode 100644 index 0000000..e994d07 --- /dev/null +++ b/man/dot-generate_paths_files.Rd @@ -0,0 +1,32 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.generate_paths_files} +\alias{.generate_paths_files} +\title{Generate files for all operations} +\usage{ +.generate_paths_files( + paths_by_operation, + api_abbr, + security_data, + pagination_data +) +} +\arguments{ +\item{paths_by_operation}{(\code{list}) Template-ready operations keyed by +operation identifier.} + +\item{api_abbr}{(\code{character(1)}) A short (about 2-5 letter) abbreviation for +the API, for use in function names and environment variables.} + +\item{security_data}{(\code{list}) Generated security metadata.} + +\item{pagination_data}{(\code{list}) Pagination metadata used while generating +path files.} +} +\value{ +A \code{character} vector of generated file paths. +} +\description{ +Generate files for all operations +} +\keyword{internal} diff --git a/man/dot-generate_paths_test_file.Rd b/man/dot-generate_paths_test_file.Rd new file mode 100644 index 0000000..0efc832 --- /dev/null +++ b/man/dot-generate_paths_test_file.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.generate_paths_test_file} +\alias{.generate_paths_test_file} +\title{Generate one tag-level test file} +\usage{ +.generate_paths_test_file(tag_operations, tag_name, api_abbr) +} +\arguments{ +\item{tag_operations}{(\code{list}) Operations grouped under one tag.} + +\item{tag_name}{(\code{character(1)}) The tag name.} + +\item{api_abbr}{(\code{character(1)}) A short (about 2-5 letter) abbreviation for +the API, for use in function names and environment variables.} +} +\value{ +(\code{character(1)}) The generated test file path. +} +\description{ +Generate one tag-level test file +} +\keyword{internal} diff --git a/man/dot-generate_pkg_impl.Rd b/man/dot-generate_pkg_impl.Rd new file mode 100644 index 0000000..fcb84df --- /dev/null +++ b/man/dot-generate_pkg_impl.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg.R +\name{.generate_pkg_impl} +\alias{.generate_pkg_impl} +\title{Generate package files from prepared inputs} +\usage{ +.generate_pkg_impl(config, api_definition, security_data) +} +\arguments{ +\item{config}{(\code{list}) Package-generation configuration data.} + +\item{api_definition}{(\code{rapid::class_rapid}) The API definition to generate +package code from.} + +\item{security_data}{(\code{list}) Generated security metadata.} +} +\value{ +A \code{character} vector of generated file paths, invisibly. +} +\description{ +Generate package files from prepared inputs +} +\keyword{internal} diff --git a/man/dot-generate_prepare.Rd b/man/dot-generate_prepare.Rd new file mode 100644 index 0000000..ff38f25 --- /dev/null +++ b/man/dot-generate_prepare.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-prepare.R +\name{.generate_prepare} +\alias{.generate_prepare} +\title{Generate prepare files} +\usage{ +.generate_prepare(config, api_definition, security_data) +} +\arguments{ +\item{config}{(\code{list}) Package-generation configuration data.} + +\item{api_definition}{(\code{rapid::class_rapid}) The API definition to generate +package code from.} + +\item{security_data}{(\code{list}) Generated security metadata.} +} +\value{ +A \code{character} vector of generated file paths. +} +\description{ +Generate prepare files +} +\keyword{internal} diff --git a/man/dot-generate_prepare_r.Rd b/man/dot-generate_prepare_r.Rd new file mode 100644 index 0000000..7ab4510 --- /dev/null +++ b/man/dot-generate_prepare_r.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-prepare.R +\name{.generate_prepare_r} +\alias{.generate_prepare_r} +\title{Generate the prepare helper} +\usage{ +.generate_prepare_r(config, api_definition, security_data) +} +\arguments{ +\item{config}{(\code{list}) Package-generation configuration data.} + +\item{api_definition}{(\code{rapid::class_rapid}) The API definition to generate +package code from.} + +\item{security_data}{(\code{list}) Generated security metadata.} +} +\value{ +(\code{character(1)}) The generated file path. +} +\description{ +Generate the prepare helper +} +\keyword{internal} diff --git a/man/dot-generate_prepare_test.Rd b/man/dot-generate_prepare_test.Rd new file mode 100644 index 0000000..55ba72f --- /dev/null +++ b/man/dot-generate_prepare_test.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-prepare.R +\name{.generate_prepare_test} +\alias{.generate_prepare_test} +\title{Generate prepare tests} +\usage{ +.generate_prepare_test(api_abbr) +} +\arguments{ +\item{api_abbr}{(\code{character(1)}) A short (about 2-5 letter) abbreviation for +the API, for use in function names and environment variables.} +} +\value{ +(\code{character(1)}) The generated test file path. +} +\description{ +Generate prepare tests +} +\keyword{internal} diff --git a/man/dot-generate_security.Rd b/man/dot-generate_security.Rd new file mode 100644 index 0000000..e7f0580 --- /dev/null +++ b/man/dot-generate_security.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-security.R +\name{.generate_security} +\alias{.generate_security} +\title{Generate security files and metadata} +\usage{ +.generate_security(api_abbr, security_schemes) +} +\arguments{ +\item{api_abbr}{(\code{character(1)}) A short (about 2-5 letter) abbreviation for +the API, for use in function names and environment variables.} + +\item{security_schemes}{(\code{rapid::class_security_schemes}) Security schemes +from the API definition.} +} +\value{ +A \code{list} of generated security metadata. +} +\description{ +Generate security files and metadata +} +\keyword{internal} diff --git a/man/dot-generate_security_arg_help.Rd b/man/dot-generate_security_arg_help.Rd new file mode 100644 index 0000000..4c9d63f --- /dev/null +++ b/man/dot-generate_security_arg_help.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-security.R +\name{.generate_security_arg_help} +\alias{.generate_security_arg_help} +\title{Build security argument help entries} +\usage{ +.generate_security_arg_help(security_scheme_collection, security_args) +} +\arguments{ +\item{security_scheme_collection}{(\code{list}) Collected security scheme +metadata.} + +\item{security_args}{(\code{character}) Security argument names to remove from +operation parameters.} +} +\value{ +A \code{list} of template-ready parameter help entries. +} +\description{ +Build security argument help entries +} +\keyword{internal} diff --git a/man/dot-generate_security_signature.Rd b/man/dot-generate_security_signature.Rd new file mode 100644 index 0000000..de37450 --- /dev/null +++ b/man/dot-generate_security_signature.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-security.R +\name{.generate_security_signature} +\alias{.generate_security_signature} +\title{Generate a security argument signature} +\usage{ +.generate_security_signature(security_arg_names, api_abbr) +} +\arguments{ +\item{security_arg_names}{(\code{character}) Security argument names to exclude +from generated operation signatures.} + +\item{api_abbr}{(\code{character(1)}) A short (about 2-5 letter) abbreviation for +the API, for use in function names and environment variables.} +} +\value{ +(\code{character(1)}) A function-signature fragment. +} +\description{ +Generate a security argument signature +} +\keyword{internal} diff --git a/man/dot-generate_shared_params.Rd b/man/dot-generate_shared_params.Rd new file mode 100644 index 0000000..27e35c7 --- /dev/null +++ b/man/dot-generate_shared_params.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-shared.R +\name{.generate_shared_params} +\alias{.generate_shared_params} +\title{Generate shared parameter docs} +\usage{ +.generate_shared_params(security_data) +} +\arguments{ +\item{security_data}{(\code{list}) Generated security metadata.} +} +\value{ +(\code{character(1)}) The generated file path. +} +\description{ +Generate shared parameter docs +} +\keyword{internal} diff --git a/man/dot-glue_pipe_brace.Rd b/man/dot-glue_pipe_brace.Rd new file mode 100644 index 0000000..1411c53 --- /dev/null +++ b/man/dot-glue_pipe_brace.Rd @@ -0,0 +1,20 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/utils.R +\name{.glue_pipe_brace} +\alias{.glue_pipe_brace} +\title{Interpolate glue with pipe braces} +\usage{ +.glue_pipe_brace(..., .envir = rlang::caller_env()) +} +\arguments{ +\item{...}{Expressions passed to \code{\link[glue:glue]{glue::glue()}}.} + +\item{.envir}{(\code{environment}) The environment in which to evaluate \code{...}.} +} +\value{ +A glue object. +} +\description{ +Interpolate glue with pipe braces +} +\keyword{internal} diff --git a/man/dot-onLoad.Rd b/man/dot-onLoad.Rd new file mode 100644 index 0000000..4f08f41 --- /dev/null +++ b/man/dot-onLoad.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/zzz.R +\name{.onLoad} +\alias{.onLoad} +\title{Register package methods on load} +\usage{ +.onLoad(...) +} +\arguments{ +\item{...}{Additional arguments passed by R during package loading.} +} +\value{ +\code{NULL} (invisibly). +} +\description{ +Register package methods on load +} +\keyword{internal} diff --git a/man/dot-param_schema_to_r.Rd b/man/dot-param_schema_to_r.Rd new file mode 100644 index 0000000..50b5af9 --- /dev/null +++ b/man/dot-param_schema_to_r.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.param_schema_to_r} +\alias{.param_schema_to_r} +\title{Map parameter schemas to \code{stbl} helpers} +\usage{ +.param_schema_to_r(params_schema) +} +\arguments{ +\item{params_schema}{(\code{data.frame}) Schema metadata for operation +parameters.} +} +\value{ +(\code{character}) Coercion helper names. +} +\description{ +Map parameter schemas to \code{stbl} helpers +} +\keyword{internal} diff --git a/man/dot-params_to_args.Rd b/man/dot-params_to_args.Rd new file mode 100644 index 0000000..b27777c --- /dev/null +++ b/man/dot-params_to_args.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.params_to_args} +\alias{.params_to_args} +\title{Convert parameters to a signature string} +\usage{ +.params_to_args(params) +} +\arguments{ +\item{params}{(\code{list}) Parameter metadata for a single operation.} +} +\value{ +(\code{character(1)}) A comma-separated parameter string. +} +\description{ +Convert parameters to a signature string +} +\keyword{internal} diff --git a/man/dot-params_to_list.Rd b/man/dot-params_to_list.Rd new file mode 100644 index 0000000..4c7e957 --- /dev/null +++ b/man/dot-params_to_list.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.params_to_list} +\alias{.params_to_list} +\title{Convert parameter rows to a list} +\usage{ +.params_to_list(params_df) +} +\arguments{ +\item{params_df}{(\code{data.frame}) Parameter metadata in tabular form.} +} +\value{ +A \code{list} of parameter metadata entries. +} +\description{ +Convert parameter rows to a list +} +\keyword{internal} diff --git a/man/dot-params_to_named_args.Rd b/man/dot-params_to_named_args.Rd new file mode 100644 index 0000000..bf0003b --- /dev/null +++ b/man/dot-params_to_named_args.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.params_to_named_args} +\alias{.params_to_named_args} +\title{Convert parameters to named arguments} +\usage{ +.params_to_named_args(params) +} +\arguments{ +\item{params}{(\code{list}) Parameter metadata for a single operation.} +} +\value{ +(\code{character(1)}) A comma-separated named-argument string. +} +\description{ +Convert parameters to named arguments +} +\keyword{internal} diff --git a/man/dot-params_to_validations.Rd b/man/dot-params_to_validations.Rd new file mode 100644 index 0000000..f512bb7 --- /dev/null +++ b/man/dot-params_to_validations.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.params_to_validations} +\alias{.params_to_validations} +\title{Convert parameters to validation metadata} +\usage{ +.params_to_validations(params) +} +\arguments{ +\item{params}{(\code{list}) Parameter metadata for a single operation.} +} +\value{ +A \code{list} of validation metadata. +} +\description{ +Convert parameters to validation metadata +} +\keyword{internal} diff --git a/man/dot-paste0_if.Rd b/man/dot-paste0_if.Rd new file mode 100644 index 0000000..cd0f731 --- /dev/null +++ b/man/dot-paste0_if.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/utils.R +\name{.paste0_if} +\alias{.paste0_if} +\title{Append text conditionally} +\usage{ +.paste0_if(original, test, addition) +} +\arguments{ +\item{original}{(\code{character}) The original text.} + +\item{test}{(\code{logical}) A condition for each element of \code{original}.} + +\item{addition}{(\code{character}) Text to append when \code{test} is \code{TRUE}.} +} +\value{ +(\code{character}) The updated text. +} +\description{ +Append text conditionally +} +\keyword{internal} diff --git a/man/dot-path_as_arg.Rd b/man/dot-path_as_arg.Rd new file mode 100644 index 0000000..cd46314 --- /dev/null +++ b/man/dot-path_as_arg.Rd @@ -0,0 +1,20 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.path_as_arg} +\alias{.path_as_arg} +\title{Convert a path to a request argument} +\usage{ +.path_as_arg(path, params_df) +} +\arguments{ +\item{path}{(\code{character(1)}) The path template.} + +\item{params_df}{(\code{data.frame}) Parameter metadata in tabular form.} +} +\value{ +(\code{character(1)}) Code for the request path argument. +} +\description{ +Convert a path to a request argument +} +\keyword{internal} diff --git a/man/dot-path_row_to_list.Rd b/man/dot-path_row_to_list.Rd new file mode 100644 index 0000000..7c070b2 --- /dev/null +++ b/man/dot-path_row_to_list.Rd @@ -0,0 +1,42 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.path_row_to_list} +\alias{.path_row_to_list} +\title{Convert one operation row to template data} +\usage{ +.path_row_to_list( + operation_id, + endpoint, + operation, + operation_summary, + operation_description, + tags, + parameters, + ... +) +} +\arguments{ +\item{operation_id}{(\code{character(1)}) The operation identifier used in +generated file names.} + +\item{endpoint}{(\code{character(1)}) The operation endpoint.} + +\item{operation}{(\code{character(1)}) The HTTP method.} + +\item{operation_summary}{(\code{character(1)}) The operation summary.} + +\item{operation_description}{(\code{character(1)}) The operation description.} + +\item{tags}{(\code{character(1)}) The operation tag.} + +\item{parameters}{(\code{data.frame}) Operation parameters.} + +\item{...}{Additional columns, ignored.} +} +\value{ +A \code{list} describing one operation. +} +\description{ +Convert one operation row to template data +} +\keyword{internal} diff --git a/man/dot-paths_fill_descriptions.Rd b/man/dot-paths_fill_descriptions.Rd new file mode 100644 index 0000000..b064906 --- /dev/null +++ b/man/dot-paths_fill_descriptions.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.paths_fill_descriptions} +\alias{.paths_fill_descriptions} +\title{Fill missing operation descriptions} +\usage{ +.paths_fill_descriptions(operation_descriptions, operation_summaries) +} +\arguments{ +\item{operation_descriptions}{(\code{character}) Operation descriptions from the +API definition.} + +\item{operation_summaries}{(\code{character}) Operation summaries from the API +definition.} +} +\value{ +(\code{character}) Operation descriptions. +} +\description{ +Fill missing operation descriptions +} +\keyword{internal} diff --git a/man/dot-paths_fill_operation_id.Rd b/man/dot-paths_fill_operation_id.Rd new file mode 100644 index 0000000..8865fc6 --- /dev/null +++ b/man/dot-paths_fill_operation_id.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.paths_fill_operation_id} +\alias{.paths_fill_operation_id} +\title{Fill missing operation identifiers} +\usage{ +.paths_fill_operation_id(operation_ids, endpoints, methods) +} +\arguments{ +\item{operation_ids}{(\code{character}) Operation identifiers from the API +definition.} + +\item{endpoints}{(\code{character}) Endpoint paths paired with operations.} + +\item{methods}{(\code{character}) HTTP methods paired with endpoints.} +} +\value{ +(\code{character}) Operation identifiers. +} +\description{ +Fill missing operation identifiers +} +\keyword{internal} diff --git a/man/dot-paths_fill_summary.Rd b/man/dot-paths_fill_summary.Rd new file mode 100644 index 0000000..aaf38f3 --- /dev/null +++ b/man/dot-paths_fill_summary.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.paths_fill_summary} +\alias{.paths_fill_summary} +\title{Fill missing operation summaries} +\usage{ +.paths_fill_summary(operation_summaries, endpoints, methods) +} +\arguments{ +\item{operation_summaries}{(\code{character}) Operation summaries from the API +definition.} + +\item{endpoints}{(\code{character}) Endpoint paths paired with operations.} + +\item{methods}{(\code{character}) HTTP methods paired with endpoints.} +} +\value{ +(\code{character}) Human-readable operation summaries. +} +\description{ +Fill missing operation summaries +} +\keyword{internal} diff --git a/man/dot-paths_fill_tags.Rd b/man/dot-paths_fill_tags.Rd new file mode 100644 index 0000000..00fb27e --- /dev/null +++ b/man/dot-paths_fill_tags.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.paths_fill_tags} +\alias{.paths_fill_tags} +\title{Fill missing operation tags} +\usage{ +.paths_fill_tags(tags) +} +\arguments{ +\item{tags}{(\code{list}) Operation tags from the API definition.} +} +\value{ +(\code{character}) Snake-case tag names. +} +\description{ +Fill missing operation tags +} +\keyword{internal} diff --git a/man/dot-paths_need_stbl.Rd b/man/dot-paths_need_stbl.Rd new file mode 100644 index 0000000..fe60136 --- /dev/null +++ b/man/dot-paths_need_stbl.Rd @@ -0,0 +1,21 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.paths_need_stbl} +\alias{.paths_need_stbl} +\title{Determine whether generated paths need \code{stbl}} +\usage{ +.paths_need_stbl(paths, security_arg_names = character()) +} +\arguments{ +\item{paths}{(\code{rapid::class_paths}) API path definitions.} + +\item{security_arg_names}{(\code{character}) Security argument names to exclude +from generated operation signatures.} +} +\value{ +(\code{logical(1)}) \code{TRUE} if any path needs \code{stbl}. +} +\description{ +Determine whether generated paths need \code{stbl} +} +\keyword{internal} diff --git a/man/dot-paths_to_clean_df.Rd b/man/dot-paths_to_clean_df.Rd new file mode 100644 index 0000000..b884725 --- /dev/null +++ b/man/dot-paths_to_clean_df.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.paths_to_clean_df} +\alias{.paths_to_clean_df} +\title{Convert API paths to an operations data frame} +\usage{ +.paths_to_clean_df(paths) +} +\arguments{ +\item{paths}{(\code{rapid::class_paths}) API path definitions.} +} +\value{ +A \code{\link[tibble:tibble]{tibble::tibble()}} with one row per non-deprecated operation. +} +\description{ +Convert API paths to an operations data frame +} +\keyword{internal} diff --git a/man/dot-prep_param_args.Rd b/man/dot-prep_param_args.Rd new file mode 100644 index 0000000..f624ad7 --- /dev/null +++ b/man/dot-prep_param_args.Rd @@ -0,0 +1,21 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.prep_param_args} +\alias{.prep_param_args} +\title{Prepare parameter arguments} +\usage{ +.prep_param_args(params, security_args) +} +\arguments{ +\item{params}{(\code{list}) Parameter metadata for a single operation.} + +\item{security_args}{(\code{character}) Security argument names to remove from +operation parameters.} +} +\value{ +(\code{character(1)}) A comma-separated named-argument string. +} +\description{ +Prepare parameter arguments +} +\keyword{internal} diff --git a/man/dot-prepare_params_df.Rd b/man/dot-prepare_params_df.Rd new file mode 100644 index 0000000..8362d54 --- /dev/null +++ b/man/dot-prepare_params_df.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.prepare_params_df} +\alias{.prepare_params_df} +\title{Prepare parameter metadata} +\usage{ +.prepare_params_df(params_df) +} +\arguments{ +\item{params_df}{(\code{data.frame}) Parameter metadata in tabular form.} +} +\value{ +A \code{data.frame} of prepared parameter metadata. +} +\description{ +Prepare parameter metadata +} +\keyword{internal} diff --git a/man/dot-remove_security_args.Rd b/man/dot-remove_security_args.Rd new file mode 100644 index 0000000..1e7bb29 --- /dev/null +++ b/man/dot-remove_security_args.Rd @@ -0,0 +1,21 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-paths.R +\name{.remove_security_args} +\alias{.remove_security_args} +\title{Remove security parameters} +\usage{ +.remove_security_args(params, security_args) +} +\arguments{ +\item{params}{(\code{list}) Parameter metadata for a single operation.} + +\item{security_args}{(\code{character}) Security argument names to remove from +operation parameters.} +} +\value{ +A \code{list} of non-security parameters. +} +\description{ +Remove security parameters +} +\keyword{internal} diff --git a/man/dot-security_arg_description_clean.Rd b/man/dot-security_arg_description_clean.Rd new file mode 100644 index 0000000..89f35e1 --- /dev/null +++ b/man/dot-security_arg_description_clean.Rd @@ -0,0 +1,20 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-security.R +\name{.security_arg_description_clean} +\alias{.security_arg_description_clean} +\title{Format one security argument help entry} +\usage{ +.security_arg_description_clean(security_arg_description, security_arg_name) +} +\arguments{ +\item{security_arg_description}{(\code{character(1)}) The argument description.} + +\item{security_arg_name}{(\code{character(1)}) The argument name.} +} +\value{ +A named \code{list} with \code{name} and \code{description}. +} +\description{ +Format one security argument help entry +} +\keyword{internal} diff --git a/man/dot-security_args_compile.Rd b/man/dot-security_args_compile.Rd new file mode 100644 index 0000000..5a37921 --- /dev/null +++ b/man/dot-security_args_compile.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-security.R +\name{.security_args_compile} +\alias{.security_args_compile} +\title{Compile security argument metadata} +\usage{ +.security_args_compile(security_scheme_collection) +} +\arguments{ +\item{security_scheme_collection}{(\code{list}) Collected security scheme +metadata.} +} +\value{ +A \code{list} of compiled security argument values. +} +\description{ +Compile security argument metadata +} +\keyword{internal} diff --git a/man/dot-security_scheme_collection_finalize.Rd b/man/dot-security_scheme_collection_finalize.Rd new file mode 100644 index 0000000..c2ae22e --- /dev/null +++ b/man/dot-security_scheme_collection_finalize.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-security.R +\name{.security_scheme_collection_finalize} +\alias{.security_scheme_collection_finalize} +\title{Finalize collected security scheme data} +\usage{ +.security_scheme_collection_finalize(security_scheme_collection) +} +\arguments{ +\item{security_scheme_collection}{(\code{list}) Collected security scheme +metadata.} +} +\value{ +A \code{list} of finalized security metadata. +} +\description{ +Finalize collected security scheme data +} +\keyword{internal} diff --git a/man/dot-security_scheme_description_fill.Rd b/man/dot-security_scheme_description_fill.Rd new file mode 100644 index 0000000..f93e9c7 --- /dev/null +++ b/man/dot-security_scheme_description_fill.Rd @@ -0,0 +1,24 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-security.R +\name{.security_scheme_description_fill} +\alias{.security_scheme_description_fill} +\title{Fill a missing security scheme description} +\usage{ +.security_scheme_description_fill( + security_scheme_description, + security_scheme_type +) +} +\arguments{ +\item{security_scheme_description}{(\code{character(1)}) A security scheme +description from the API definition.} + +\item{security_scheme_type}{(\code{character(1)}) The security scheme type.} +} +\value{ +(\code{character(1)}) A security scheme description. +} +\description{ +Fill a missing security scheme description +} +\keyword{internal} diff --git a/man/dot-security_scheme_rotate.Rd b/man/dot-security_scheme_rotate.Rd new file mode 100644 index 0000000..b048fb4 --- /dev/null +++ b/man/dot-security_scheme_rotate.Rd @@ -0,0 +1,28 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-security.R +\name{.security_scheme_rotate} +\alias{.security_scheme_rotate} +\title{Convert one security scheme to a list} +\usage{ +.security_scheme_rotate( + security_scheme_name, + security_scheme_details, + security_scheme_description +) +} +\arguments{ +\item{security_scheme_name}{(\code{character(1)}) The security scheme name.} + +\item{security_scheme_details}{(\code{rapid::class_security_scheme_details}) The +security scheme details.} + +\item{security_scheme_description}{(\code{character(1)}) A security scheme +description from the API definition.} +} +\value{ +A \code{list} describing one security scheme. +} +\description{ +Convert one security scheme to a list +} +\keyword{internal} diff --git a/man/dot-security_schemes_collect.Rd b/man/dot-security_schemes_collect.Rd new file mode 100644 index 0000000..095fef8 --- /dev/null +++ b/man/dot-security_schemes_collect.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-security.R +\name{.security_schemes_collect} +\alias{.security_schemes_collect} +\title{Collect security scheme metadata} +\usage{ +.security_schemes_collect(security_schemes) +} +\arguments{ +\item{security_schemes}{(\code{rapid::class_security_schemes}) Security schemes +from the API definition.} +} +\value{ +A \code{list} of security scheme metadata. +} +\description{ +Collect security scheme metadata +} +\keyword{internal} diff --git a/man/dot-setup_r.Rd b/man/dot-setup_r.Rd new file mode 100644 index 0000000..7596659 --- /dev/null +++ b/man/dot-setup_r.Rd @@ -0,0 +1,21 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-setup.R +\name{.setup_r} +\alias{.setup_r} +\title{Set up package directories and dependencies} +\usage{ +.setup_r(pkg_dir, include_stbl = FALSE) +} +\arguments{ +\item{pkg_dir}{(\code{character(1)} or \code{fs_path}) The directory containing package +files.} + +\item{include_stbl}{(\code{logical(1)}) Whether to add \code{stbl} to Imports.} +} +\value{ +\code{NULL} (invisibly). +} +\description{ +Set up package directories and dependencies +} +\keyword{internal} diff --git a/man/dot-shared-params.Rd b/man/dot-shared-params.Rd index ac04ee7..a61b0e5 100644 --- a/man/dot-shared-params.Rd +++ b/man/dot-shared-params.Rd @@ -4,6 +4,9 @@ \alias{.shared-params} \title{Shared parameters} \arguments{ +\item{allow_empty}{(\code{logical}) Whether empty parameter values may be +represented as \code{NULL}.} + \item{api_abbr}{(\code{character(1)}) A short (about 2-5 letter) abbreviation for the API, for use in function names and environment variables.} @@ -15,15 +18,67 @@ files.} \item{call}{(\code{environment}) The caller environment for error messages.} +\item{config}{(\code{list}) Package-generation configuration data.} + \item{config_file}{(\code{character(1)} or \code{fs_path}) The path to a beekeeper yaml config file.} +\item{data}{(\code{list}) Data passed to a template.} + +\item{dir}{(\code{character(1)}) The directory where a generated file should be +written.} + +\item{endpoints}{(\code{character}) Endpoint paths paired with operations.} + +\item{methods}{(\code{character}) HTTP methods paired with endpoints.} + +\item{operation_id}{(\code{character(1)}) The operation identifier used in +generated file names.} + +\item{operation_summaries}{(\code{character}) Operation summaries from the API +definition.} + +\item{pagination_data}{(\code{list}) Pagination metadata used while generating +path files.} + +\item{params}{(\code{list}) Parameter metadata for a single operation.} + +\item{params_df}{(\code{data.frame}) Parameter metadata in tabular form.} + +\item{params_schema}{(\code{data.frame}) Schema metadata for operation +parameters.} + +\item{paths}{(\code{rapid::class_paths}) API path definitions.} + \item{pkg_dir}{(\code{character(1)} or \code{fs_path}) The directory containing package files.} \item{rapid_file}{(\code{character(1)} or \code{fs_path}) The path to the R API definition (rapid) file.} +\item{required}{(\code{logical}) Whether each parameter is required.} + +\item{security_arg_names}{(\code{character}) Security argument names to exclude +from generated operation signatures.} + +\item{security_args}{(\code{character}) Security argument names to remove from +operation parameters.} + +\item{security_data}{(\code{list}) Generated security metadata.} + +\item{security_scheme_collection}{(\code{list}) Collected security scheme +metadata.} + +\item{security_scheme_description}{(\code{character(1)}) A security scheme +description from the API definition.} + +\item{security_schemes}{(\code{rapid::class_security_schemes}) Security schemes +from the API definition.} + +\item{target}{(\code{character(1)}) The name of the generated file.} + +\item{template}{(\code{character(1)}) The template file name to render.} + \item{to_collapse}{(\code{character}) The character vector to collapse.} } \description{ diff --git a/man/dot-stabilize_config.Rd b/man/dot-stabilize_config.Rd new file mode 100644 index 0000000..990d7cd --- /dev/null +++ b/man/dot-stabilize_config.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/generate_pkg-setup.R +\name{.stabilize_config} +\alias{.stabilize_config} +\title{Stabilize beekeeper config values} +\usage{ +.stabilize_config(config) +} +\arguments{ +\item{config}{(\code{list}) Package-generation configuration data.} +} +\value{ +A stabilized \code{list}. +} +\description{ +Stabilize beekeeper config values +} +\keyword{internal} diff --git a/man/dot-to_snake.Rd b/man/dot-to_snake.Rd new file mode 100644 index 0000000..b0b5f1c --- /dev/null +++ b/man/dot-to_snake.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/utils.R +\name{.to_snake} +\alias{.to_snake} +\title{Convert text to snake case} +\usage{ +.to_snake(x) +} +\arguments{ +\item{x}{(\code{character}) Text to convert.} +} +\value{ +(\code{character}) Snake-case text. +} +\description{ +Convert text to snake case +} +\keyword{internal} diff --git a/man/dot-write_config.Rd b/man/dot-write_config.Rd new file mode 100644 index 0000000..cd3ec2a --- /dev/null +++ b/man/dot-write_config.Rd @@ -0,0 +1,28 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/use_beekeeper.R +\name{.write_config} +\alias{.write_config} +\title{Write the beekeeper config file} +\usage{ +.write_config(api_definition, api_abbr, rapid_file, config_file) +} +\arguments{ +\item{api_definition}{(\code{rapid::class_rapid}) The API definition to generate +package code from.} + +\item{api_abbr}{(\code{character(1)}) A short (about 2-5 letter) abbreviation for +the API, for use in function names and environment variables.} + +\item{rapid_file}{(\code{character(1)} or \code{fs_path}) The path to the R API +definition (rapid) file.} + +\item{config_file}{(\code{character(1)} or \code{fs_path}) The path to a beekeeper yaml +config file.} +} +\value{ +(\code{character(1)}) The written config file path. +} +\description{ +Write the beekeeper config file +} +\keyword{internal} diff --git a/man/dot-write_rapid.Rd b/man/dot-write_rapid.Rd new file mode 100644 index 0000000..45c7333 --- /dev/null +++ b/man/dot-write_rapid.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/use_beekeeper.R +\name{.write_rapid} +\alias{.write_rapid} +\title{Write the rapid definition file} +\usage{ +.write_rapid(api_definition, rapid_file) +} +\arguments{ +\item{api_definition}{(\code{rapid::class_rapid}) The API definition to generate +package code from.} + +\item{rapid_file}{(\code{character(1)} or \code{fs_path}) The path to the R API +definition (rapid) file.} +} +\value{ +(\code{character(1)}) The written file path. +} +\description{ +Write the rapid definition file +} +\keyword{internal} diff --git a/tests/testthat/test-documentation.R b/tests/testthat/test-documentation.R new file mode 100644 index 0000000..b5e44d2 --- /dev/null +++ b/tests/testthat/test-documentation.R @@ -0,0 +1,66 @@ +test_that("internal helpers have roxygen docs (#noissue)", { + r_files <- fs::dir_ls( + test_path("..", "..", "R"), + glob = "*.R", + recurse = FALSE + ) + r_files <- r_files[!grepl("import-standalone-", r_files)] + missing_docs <- character() + + has_roxygen_block <- function(lines, line_number) { + previous <- line_number - 1L + while (previous > 0L && !nzchar(trimws(lines[[previous]]))) { + previous <- previous - 1L + } + previous > 0L && startsWith(trimws(lines[[previous]]), "#'") + } + + for (path in r_files) { + lines <- readLines(path) + + for (line_number in seq_along(lines)) { + line <- lines[[line_number]] + regular_match <- regexec( + "^(`[^`]+`|[A-Za-z0-9._]+)\\s*<-\\s*function\\(", + line + )[[1]] + method_match <- grepl( + "^S7::method\\([^\\n]+\\)\\s*<-\\s*function\\(", + line + ) + + if (regular_match[1] != -1L) { + object_name <- regmatches( + line, + regexec( + "^(`[^`]+`|[A-Za-z0-9._]+)\\s*<-\\s*function\\(", + line + ) + )[[1]][2] + } else { + object_name <- NULL + } + + if ( + (is.null(object_name) && !method_match) || + has_roxygen_block(lines, line_number) + ) { + next + } + + if (method_match) { + missing_docs <- c( + missing_docs, + paste0(basename(path), "::S7_method@", line_number) + ) + } else { + missing_docs <- c( + missing_docs, + paste0(basename(path), "::", object_name) + ) + } + } + } + + expect_identical(missing_docs, character()) +}) From 84473f8641c2e044e7cb22393558195b21f69b37 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 16 May 2026 19:04:18 +0000 Subject: [PATCH 03/13] Polish internal documentation test Agent-Logs-Url: https://github.com/api2r/beekeeper/sessions/fbf4f879-da36-4e65-975f-6ef573695aa6 Co-authored-by: jonthegeek <33983824+jonthegeek@users.noreply.github.com> --- R/as_bk_data.R | 2 +- R/generate_pkg-paths.R | 2 +- R/generate_pkg-security.R | 6 ++--- man/as_bk_data.Rd | 10 ++++---- tests/testthat/test-documentation.R | 40 +++++++++++++++++------------ 5 files changed, 33 insertions(+), 27 deletions(-) diff --git a/R/as_bk_data.R b/R/as_bk_data.R index 2df1bdd..be7137f 100644 --- a/R/as_bk_data.R +++ b/R/as_bk_data.R @@ -11,7 +11,7 @@ as_bk_data <- S7::new_generic("as_bk_data", dispatch_args = "x") #' @rdname as_bk_data #' @keywords internal -S7::method(as_bk_data, class_any) <- function(x) { +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()) } diff --git a/R/generate_pkg-paths.R b/R/generate_pkg-paths.R index 22aa1aa..9281997 100644 --- a/R/generate_pkg-paths.R +++ b/R/generate_pkg-paths.R @@ -35,7 +35,7 @@ #' @rdname as_bk_data #' @keywords internal -S7::method(as_bk_data, class_paths) <- function(x) { +S7::method(as_bk_data, class_paths) <- function(x, ...) { if (!length(x)) { return(list()) } diff --git a/R/generate_pkg-security.R b/R/generate_pkg-security.R index c8473eb..4c2315b 100644 --- a/R/generate_pkg-security.R +++ b/R/generate_pkg-security.R @@ -34,7 +34,7 @@ #' @rdname as_bk_data #' @keywords internal -S7::method(as_bk_data, class_security_schemes) <- function(x) { +S7::method(as_bk_data, class_security_schemes) <- function(x, ...) { if (!length(x)) { return(list()) } @@ -191,13 +191,13 @@ S7::method(as_bk_data, class_security_schemes) <- function(x) { #' @rdname as_bk_data #' @keywords internal -S7::method(as_bk_data, class_security_scheme_details) <- function(x) { +S7::method(as_bk_data, class_security_scheme_details) <- function(x, ...) { purrr::map(x, as_bk_data) } #' @rdname as_bk_data #' @keywords internal -S7::method(as_bk_data, class_api_key_security_scheme) <- function(x) { +S7::method(as_bk_data, class_api_key_security_scheme) <- function(x, ...) { if (length(x)) { return( list( diff --git a/man/as_bk_data.Rd b/man/as_bk_data.Rd index e5b8a00..9a262d8 100644 --- a/man/as_bk_data.Rd +++ b/man/as_bk_data.Rd @@ -13,19 +13,19 @@ as_bk_data(x, ...) ## S7 method for class -as_bk_data(x) +as_bk_data(x, ...) ## S7 method for class -as_bk_data(x) +as_bk_data(x, ...) ## S7 method for class -as_bk_data(x) +as_bk_data(x, ...) ## S7 method for class -as_bk_data(x) +as_bk_data(x, ...) ## S7 method for class -as_bk_data(x) +as_bk_data(x, ...) } \arguments{ \item{x}{The object to coerce.} diff --git a/tests/testthat/test-documentation.R b/tests/testthat/test-documentation.R index b5e44d2..fe03c0f 100644 --- a/tests/testthat/test-documentation.R +++ b/tests/testthat/test-documentation.R @@ -1,10 +1,15 @@ test_that("internal helpers have roxygen docs (#noissue)", { + function_definition_pattern <- "^(`[^`]+`|[A-Za-z0-9._]+)\\s*<-\\s*function\\(" + standalone_pattern <- "import-standalone-" + r_dir <- test_path("..", "..", "R") + skip_if_not(fs::dir_exists(r_dir), "R source files are not available.") + r_files <- fs::dir_ls( - test_path("..", "..", "R"), + r_dir, glob = "*.R", recurse = FALSE ) - r_files <- r_files[!grepl("import-standalone-", r_files)] + r_files <- r_files[!grepl(standalone_pattern, r_files)] missing_docs <- character() has_roxygen_block <- function(lines, line_number) { @@ -20,23 +25,24 @@ test_that("internal helpers have roxygen docs (#noissue)", { for (line_number in seq_along(lines)) { line <- lines[[line_number]] - regular_match <- regexec( - "^(`[^`]+`|[A-Za-z0-9._]+)\\s*<-\\s*function\\(", - line - )[[1]] - method_match <- grepl( - "^S7::method\\([^\\n]+\\)\\s*<-\\s*function\\(", - line - ) + regular_match <- regexec(function_definition_pattern, line)[[1]] + method_match <- FALSE + if (grepl("^S7::method\\(", line)) { + lookahead <- paste( + lines[line_number:min(line_number + 5L, length(lines))], + collapse = " " + ) + method_match <- grepl( + "S7::method\\(.*\\)\\s*<-\\s*function\\(", + lookahead + ) + } if (regular_match[1] != -1L) { - object_name <- regmatches( - line, - regexec( - "^(`[^`]+`|[A-Za-z0-9._]+)\\s*<-\\s*function\\(", - line - ) - )[[1]][2] + object_name <- regmatches(line, regexec( + function_definition_pattern, + line + ))[[1]][2] } else { object_name <- NULL } From 8228c70cf41960894f621001000ed1feb96aa5e8 Mon Sep 17 00:00:00 2001 From: Jon Harmon Date: Sat, 16 May 2026 14:14:07 -0500 Subject: [PATCH 04/13] Delete test-documentation.R --- tests/testthat/test-documentation.R | 72 ----------------------------- 1 file changed, 72 deletions(-) delete mode 100644 tests/testthat/test-documentation.R diff --git a/tests/testthat/test-documentation.R b/tests/testthat/test-documentation.R deleted file mode 100644 index fe03c0f..0000000 --- a/tests/testthat/test-documentation.R +++ /dev/null @@ -1,72 +0,0 @@ -test_that("internal helpers have roxygen docs (#noissue)", { - function_definition_pattern <- "^(`[^`]+`|[A-Za-z0-9._]+)\\s*<-\\s*function\\(" - standalone_pattern <- "import-standalone-" - r_dir <- test_path("..", "..", "R") - skip_if_not(fs::dir_exists(r_dir), "R source files are not available.") - - r_files <- fs::dir_ls( - r_dir, - glob = "*.R", - recurse = FALSE - ) - r_files <- r_files[!grepl(standalone_pattern, r_files)] - missing_docs <- character() - - has_roxygen_block <- function(lines, line_number) { - previous <- line_number - 1L - while (previous > 0L && !nzchar(trimws(lines[[previous]]))) { - previous <- previous - 1L - } - previous > 0L && startsWith(trimws(lines[[previous]]), "#'") - } - - for (path in r_files) { - lines <- readLines(path) - - for (line_number in seq_along(lines)) { - line <- lines[[line_number]] - regular_match <- regexec(function_definition_pattern, line)[[1]] - method_match <- FALSE - if (grepl("^S7::method\\(", line)) { - lookahead <- paste( - lines[line_number:min(line_number + 5L, length(lines))], - collapse = " " - ) - method_match <- grepl( - "S7::method\\(.*\\)\\s*<-\\s*function\\(", - lookahead - ) - } - - if (regular_match[1] != -1L) { - object_name <- regmatches(line, regexec( - function_definition_pattern, - line - ))[[1]][2] - } else { - object_name <- NULL - } - - if ( - (is.null(object_name) && !method_match) || - has_roxygen_block(lines, line_number) - ) { - next - } - - if (method_match) { - missing_docs <- c( - missing_docs, - paste0(basename(path), "::S7_method@", line_number) - ) - } else { - missing_docs <- c( - missing_docs, - paste0(basename(path), "::", object_name) - ) - } - } - } - - expect_identical(missing_docs, character()) -}) From 3037b35305ed438117e134dfcfbd748fc387116e Mon Sep 17 00:00:00 2001 From: Jon Harmon Date: Sat, 16 May 2026 16:32:57 -0500 Subject: [PATCH 05/13] Tweaks to helper docs --- R/aaa-shared_params.R | 41 +++++++++++++-- R/as_bk_data.R | 3 +- R/generate_pkg-pagination.R | 2 +- R/generate_pkg-paths.R | 22 +------- R/generate_pkg-security.R | 7 +-- R/generate_pkg-setup.R | 13 ++--- R/generate_pkg-template.R | 6 +-- R/utils.R | 50 ++++++------------- R/zzz.R | 5 -- man/as_bk_data.Rd | 2 +- man/dot-assert_is_pkg.Rd | 5 +- man/dot-bk_use_template.Rd | 9 ++-- man/dot-collapse_comma_self_equal.Rd | 5 +- man/dot-describe_param_classes.Rd | 3 +- man/dot-flatten_df.Rd | 8 +++ man/dot-flatten_df_data_frame.Rd | 18 ------- man/dot-flatten_df_list.Rd | 18 ------- man/dot-flatten_df_null.Rd | 18 ------- man/dot-generate_pagination.Rd | 2 +- man/dot-generate_security_arg_help.Rd | 2 +- man/dot-generate_security_signature.Rd | 3 +- man/dot-is_pkg.Rd | 5 +- man/dot-onLoad.Rd | 18 ------- man/dot-param_schema_to_r.Rd | 3 +- man/dot-path_row_to_list.Rd | 2 +- man/dot-paths_fill_tags.Rd | 2 +- man/dot-paths_need_stbl.Rd | 3 +- man/dot-prep_param_args.Rd | 2 +- man/dot-remove_security_args.Rd | 2 +- man/dot-shared-params.Rd | 69 ++++++++++++++++++++++++-- man/op-lengthless-default.Rd | 4 +- man/op-na-coalesce.Rd | 2 +- man/op-no-char-default.Rd | 4 +- man/op-null-continuation.Rd | 4 +- man/op-null-default.Rd | 4 +- 35 files changed, 167 insertions(+), 199 deletions(-) delete mode 100644 man/dot-flatten_df_data_frame.Rd delete mode 100644 man/dot-flatten_df_list.Rd delete mode 100644 man/dot-flatten_df_null.Rd delete mode 100644 man/dot-onLoad.Rd diff --git a/R/aaa-shared_params.R b/R/aaa-shared_params.R index 753469d..a3c0675 100644 --- a/R/aaa-shared_params.R +++ b/R/aaa-shared_params.R @@ -3,6 +3,7 @@ #' 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 @@ -11,6 +12,9 @@ #' 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 @@ -18,38 +22,67 @@ #' @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 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. +#' from generated operation signatures (because they are defined once, +#' separately). #' @param security_args (`character`) Security argument names to remove from -#' operation parameters. +#' 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 diff --git a/R/as_bk_data.R b/R/as_bk_data.R index be7137f..72b964f 100644 --- a/R/as_bk_data.R +++ b/R/as_bk_data.R @@ -2,9 +2,8 @@ #' #' 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. #' @keywords internal as_bk_data <- S7::new_generic("as_bk_data", dispatch_args = "x") diff --git a/R/generate_pkg-pagination.R b/R/generate_pkg-pagination.R index 527531b..5b03b05 100644 --- a/R/generate_pkg-pagination.R +++ b/R/generate_pkg-pagination.R @@ -1,6 +1,6 @@ #' Generate pagination files #' -#' @returns An empty `list`. +#' @returns A `list` of pagination metadata used while generating path files. #' @keywords internal .generate_pagination <- function() { # TODO: Accept pagination config and generate 030-pagination.R (#63) diff --git a/R/generate_pkg-paths.R b/R/generate_pkg-paths.R index 9281997..fdad49b 100644 --- a/R/generate_pkg-paths.R +++ b/R/generate_pkg-paths.R @@ -1,7 +1,5 @@ #' Generate files for API paths #' -#' @param base_url (`character(1)`) The base URL used in generated test -#' helpers. #' @inheritParams .shared-params #' @returns A `character` vector of generated file paths. #' @keywords internal @@ -86,7 +84,7 @@ S7::method(as_bk_data, class_paths) <- function(x, ...) { #' Fill missing operation tags #' -#' @param tags (`list`) Operation tags from the API definition. +#' @inheritParams .shared-params #' @returns (`character`) Snake-case tag names. #' @keywords internal .paths_fill_tags <- function(tags) { @@ -97,8 +95,6 @@ S7::method(as_bk_data, class_paths) <- function(x, ...) { #' Fill missing operation identifiers #' -#' @param operation_ids (`character`) Operation identifiers from the API -#' definition. #' @inheritParams .shared-params #' @returns (`character`) Operation identifiers. #' @keywords internal @@ -119,8 +115,6 @@ S7::method(as_bk_data, class_paths) <- function(x, ...) { #' Fill missing operation descriptions #' -#' @param operation_descriptions (`character`) Operation descriptions from the -#' API definition. #' @inheritParams .shared-params #' @returns (`character`) Operation descriptions. #' @keywords internal @@ -141,12 +135,6 @@ S7::method(as_bk_data, class_paths) <- function(x, ...) { #' Convert one operation row to template data #' -#' @param endpoint (`character(1)`) The operation endpoint. -#' @param operation (`character(1)`) The HTTP method. -#' @param operation_summary (`character(1)`) The operation summary. -#' @param operation_description (`character(1)`) The operation description. -#' @param tags (`character(1)`) The operation tag. -#' @param parameters (`data.frame`) Operation parameters. #' @param ... Additional columns, ignored. #' @inheritParams .shared-params #' @returns A `list` describing one operation. @@ -236,7 +224,6 @@ S7::method(as_bk_data, class_paths) <- function(x, ...) { #' Extract parameter names by location #' -#' @param filter_in (`character(1)`) The parameter location to keep. #' @inheritParams .shared-params #' @returns (`character`) Parameter names for the requested location. #' @keywords internal @@ -289,7 +276,6 @@ S7::method(as_bk_data, class_paths) <- function(x, ...) { #' Compile parameter class descriptions #' -#' @param type (`data.frame`) Joined parameter type metadata. #' @inheritParams .shared-params #' @returns (`character`) Parameter class descriptions. #' @keywords internal @@ -309,7 +295,6 @@ S7::method(as_bk_data, class_paths) <- function(x, ...) { #' Convert a path to a request argument #' -#' @param path (`character(1)`) The path template. #' @inheritParams .shared-params #' @returns (`character(1)`) Code for the request path argument. #' @keywords internal @@ -326,8 +311,6 @@ S7::method(as_bk_data, class_paths) <- function(x, ...) { #' Generate files for all operations #' -#' @param paths_by_operation (`list`) Template-ready operations keyed by -#' operation identifier. #' @inheritParams .shared-params #' @returns A `character` vector of generated file paths. #' @keywords internal @@ -461,7 +444,6 @@ S7::method(as_bk_data, class_paths) <- function(x, ...) { #' Generate one operation file #' -#' @param path_operation (`list`) Template data for one operation. #' @inheritParams .shared-params #' @returns (`character(1)`) The generated file path. #' @keywords internal @@ -490,8 +472,6 @@ S7::method(as_bk_data, class_paths) <- function(x, ...) { #' Generate one tag-level test file #' -#' @param tag_operations (`list`) Operations grouped under one tag. -#' @param tag_name (`character(1)`) The tag name. #' @inheritParams .shared-params #' @returns (`character(1)`) The generated test file path. #' @keywords internal diff --git a/R/generate_pkg-security.R b/R/generate_pkg-security.R index 4c2315b..5043e1c 100644 --- a/R/generate_pkg-security.R +++ b/R/generate_pkg-security.R @@ -61,9 +61,6 @@ S7::method(as_bk_data, class_security_schemes) <- function(x, ...) { #' Convert one security scheme to a list #' -#' @param security_scheme_name (`character(1)`) The security scheme name. -#' @param security_scheme_details (`rapid::class_security_scheme_details`) The -#' security scheme details. #' @inheritParams .shared-params #' @returns A `list` describing one security scheme. #' @keywords internal @@ -88,7 +85,6 @@ S7::method(as_bk_data, class_security_schemes) <- function(x, ...) { #' Fill a missing security scheme description #' -#' @param security_scheme_type (`character(1)`) The security scheme type. #' @inheritParams .shared-params #' @returns (`character(1)`) A security scheme description. #' @keywords internal @@ -178,8 +174,7 @@ S7::method(as_bk_data, class_security_schemes) <- function(x, ...) { #' Format one security argument help entry #' -#' @param security_arg_description (`character(1)`) The argument description. -#' @param security_arg_name (`character(1)`) The argument name. +#' @inheritParams .shared-params #' @returns A named `list` with `name` and `description`. #' @keywords internal .security_arg_description_clean <- function( diff --git a/R/generate_pkg-setup.R b/R/generate_pkg-setup.R index ed312f3..5c479f2 100644 --- a/R/generate_pkg-setup.R +++ b/R/generate_pkg-setup.R @@ -4,13 +4,13 @@ #' #' @returns `NULL`, invisibly. #' @keywords internal -.assert_is_pkg <- function(base_path = usethis::proj_get()) { - if (.is_pkg(base_path)) { +.assert_is_pkg <- function(pkg_dir = usethis::proj_get()) { + if (.is_pkg(pkg_dir)) { return(invisible(NULL)) } cli::cli_abort(c( "Can't generate package files outside of a package.", - x = "{.path {base_path}} is not inside a package." + x = "{.path {pkg_dir}} is not inside a package." )) } @@ -18,13 +18,11 @@ #' #' Inspired by usethis:::is_package. #' -#' @param base_path The root URL of the current project. -#' #' @returns `TRUE` if the project is a package, `FALSE` if not. #' @keywords internal -.is_pkg <- function(base_path = usethis::proj_get()) { +.is_pkg <- function(pkg_dir = usethis::proj_get()) { root_file <- rlang::try_fetch( - rprojroot::find_package_root_file(path = base_path), + rprojroot::find_package_root_file(path = pkg_dir), error = function(cnd) NULL ) !is.null(root_file) @@ -99,7 +97,6 @@ read_api_definition <- function( #' Set up package directories and dependencies #' -#' @param include_stbl (`logical(1)`) Whether to add `stbl` to Imports. #' @inheritParams .shared-params #' @returns `NULL` (invisibly). #' @keywords internal diff --git a/R/generate_pkg-template.R b/R/generate_pkg-template.R index 1cf1677..b769d6f 100644 --- a/R/generate_pkg-template.R +++ b/R/generate_pkg-template.R @@ -1,11 +1,7 @@ #' Use a template in this package #' +#' @inheritParams .shared-params #' @inheritParams rlang::args_dots_empty -#' @param template The name of the template. -#' @param data A list of variables to apply to the template. -#' @param target The name of the file to create. -#' @param dir The directory where the file should be created. -#' #' @returns The path to the generated or updated file, invisibly. #' @keywords internal .bk_use_template <- function( diff --git a/R/utils.R b/R/utils.R index a17f107..c093c81 100644 --- a/R/utils.R +++ b/R/utils.R @@ -1,7 +1,6 @@ #' Default value for `NULL` #' -#' @param x (`any`) Object to check. -#' @param y (`any`) Default value for `x`. +#' @inheritParams .shared-params #' @returns If `x` is `NULL`, will return `y`; otherwise returns `x`. #' @name op-null-default #' @family empty operators @@ -17,8 +16,7 @@ if (exists("%||%", envir = baseenv())) { #' Default value for non-`NULL` #' -#' @param x (`any`) Object to check. -#' @param y (`any`) Default value for non-`NULL` `x`. +#' @inheritParams .shared-params #' @returns If `x` is `NULL`, will return `x`; otherwise returns `y`. #' @name op-null-continuation #' @family empty operators @@ -29,8 +27,7 @@ if (exists("%||%", envir = baseenv())) { #' Default value for length 0 #' -#' @param x (`any`) Object to check. -#' @param y (`any`) Default value for `x`. +#' @inheritParams .shared-params #' @returns If `!length(x)`, will return `x`; otherwise returns `y`. #' @keywords internal #' @name op-lengthless-default @@ -42,8 +39,8 @@ if (exists("%||%", envir = baseenv())) { #' Default value for empty strings #' -#' @param x (`any`) Object to check. -#' @param y (`character`) Default value for `x`. +#' @param y (`character`) The default value. +#' @inheritParams .shared-params #' @returns If `!nzchar(x)`, will return `y`; otherwise returns `x`. #' @keywords internal #' @name op-no-char-default @@ -59,9 +56,9 @@ if (exists("%||%", envir = baseenv())) { #' Default value for NA elements in vectors #' -#' @param x (`any`) A vector that may contain `NA` elements. #' @param y (`any`, coercible to the same class as `x`) A value or vector to #' replace `NA` elements in `x`. Will be recycled to the same length as `x`. +#' @inheritParams .shared-params #' @returns A vector of the same length as `x`, where each `NA` element in `x` #' is replaced by the corresponding element in `y`. #' @keywords internal @@ -104,15 +101,13 @@ if (exists("%||%", envir = baseenv())) { #' @inheritParams .shared-params #' @returns A length-1, comma-separated glue object. #' @keywords internal -.collapse_comma_self_equal <- function(x) { - .collapse_comma(glue::glue("{x} = {x}")) +.collapse_comma_self_equal <- function(to_collapse) { + .collapse_comma(glue::glue("{to_collapse} = {to_collapse}")) } #' Append text conditionally #' -#' @param original (`character`) The original text. -#' @param test (`logical`) A condition for each element of `original`. -#' @param addition (`character`) Text to append when `test` is `TRUE`. +#' @inheritParams .shared-params #' @returns (`character`) The updated text. #' @keywords internal .paste0_if <- function(original, test, addition) { @@ -147,29 +142,12 @@ if (exists("%||%", envir = baseenv())) { #' @keywords internal .flatten_df <- S7::new_generic(".flatten_df", dispatch_args = "x") -#' Flatten a data frame method -#' -#' @param x (`data.frame`) The object to return unchanged. -#' @returns A `data.frame`. +#' @rdname dot-flatten_df #' @keywords internal -.flatten_df_data_frame <- function(x) x +S7::method(.flatten_df, class_data.frame) <- function(x) x -S7::method(.flatten_df, class_data.frame) <- .flatten_df_data_frame - -#' Flatten a list method -#' -#' @param x (`list`) The objects to row-bind. -#' @returns A `data.frame`. -#' @keywords internal -.flatten_df_list <- function(x) purrr::list_rbind(x) - -S7::method(.flatten_df, class_list) <- .flatten_df_list - -#' Flatten a `NULL` method -#' -#' @param x (`NULL`) The object to convert. -#' @returns A `data.frame`. +#' @rdname dot-flatten_df #' @keywords internal -.flatten_df_null <- function(x) data.frame() +S7::method(.flatten_df, class_list) <- function(x) purrr::list_rbind(x) -S7::method(.flatten_df, NULL) <- .flatten_df_null +S7::method(.flatten_df, NULL) <- function(x) data.frame() diff --git a/R/zzz.R b/R/zzz.R index cf702e7..0b7eb0c 100644 --- a/R/zzz.R +++ b/R/zzz.R @@ -1,8 +1,3 @@ -#' Register package methods on load -#' -#' @param ... Additional arguments passed by R during package loading. -#' @returns `NULL` (invisibly). -#' @keywords internal .onLoad <- function(...) { S7::methods_register() # nocov } diff --git a/man/as_bk_data.Rd b/man/as_bk_data.Rd index 9a262d8..40f2a8e 100644 --- a/man/as_bk_data.Rd +++ b/man/as_bk_data.Rd @@ -28,7 +28,7 @@ as_bk_data(x, ...) as_bk_data(x, ...) } \arguments{ -\item{x}{The object to coerce.} +\item{x}{(\code{any}) The object to check or coerce.} \item{...}{These dots are for future extensions and must be empty.} } diff --git a/man/dot-assert_is_pkg.Rd b/man/dot-assert_is_pkg.Rd index 31c1b6c..f8986b8 100644 --- a/man/dot-assert_is_pkg.Rd +++ b/man/dot-assert_is_pkg.Rd @@ -4,10 +4,7 @@ \alias{.assert_is_pkg} \title{Error if not in package} \usage{ -.assert_is_pkg(base_path = usethis::proj_get()) -} -\arguments{ -\item{base_path}{The root URL of the current project.} +.assert_is_pkg(pkg_dir = usethis::proj_get()) } \value{ \code{NULL}, invisibly. diff --git a/man/dot-bk_use_template.Rd b/man/dot-bk_use_template.Rd index 4ac8f9e..3b166c9 100644 --- a/man/dot-bk_use_template.Rd +++ b/man/dot-bk_use_template.Rd @@ -13,15 +13,16 @@ ) } \arguments{ -\item{template}{The name of the template.} +\item{template}{(\code{character(1)}) The template file name to render.} -\item{data}{A list of variables to apply to the template.} +\item{data}{(\code{list}) Data passed to a template.} \item{...}{These dots are for future extensions and must be empty.} -\item{target}{The name of the file to create.} +\item{target}{(\code{character(1)}) The name of the generated file.} -\item{dir}{The directory where the file should be created.} +\item{dir}{(\code{character(1)}) The directory where a generated file should be +written.} } \value{ The path to the generated or updated file, invisibly. diff --git a/man/dot-collapse_comma_self_equal.Rd b/man/dot-collapse_comma_self_equal.Rd index 12748ed..73222fd 100644 --- a/man/dot-collapse_comma_self_equal.Rd +++ b/man/dot-collapse_comma_self_equal.Rd @@ -4,7 +4,10 @@ \alias{.collapse_comma_self_equal} \title{Collapse to a comma-separated x = x string} \usage{ -.collapse_comma_self_equal(x) +.collapse_comma_self_equal(to_collapse) +} +\arguments{ +\item{to_collapse}{(\code{character}) The character vector to collapse.} } \value{ A length-1, comma-separated glue object. diff --git a/man/dot-describe_param_classes.Rd b/man/dot-describe_param_classes.Rd index c89a275..e94c684 100644 --- a/man/dot-describe_param_classes.Rd +++ b/man/dot-describe_param_classes.Rd @@ -7,8 +7,7 @@ .describe_param_classes(params_schema, allow_empty, required) } \arguments{ -\item{params_schema}{(\code{data.frame}) Schema metadata for operation -parameters.} +\item{params_schema}{(\code{data.frame}) Schema metadata for operation parameters.} \item{allow_empty}{(\code{logical}) Whether empty parameter values may be represented as \code{NULL}.} diff --git a/man/dot-flatten_df.Rd b/man/dot-flatten_df.Rd index 2d5ad8f..50e57a7 100644 --- a/man/dot-flatten_df.Rd +++ b/man/dot-flatten_df.Rd @@ -2,9 +2,17 @@ % Please edit documentation in R/utils.R \name{.flatten_df} \alias{.flatten_df} +\alias{.flatten_df,data.frame-method} +\alias{.flatten_df,list-method} \title{Flatten a data frame or list of data frames} \usage{ .flatten_df(x, ...) + +## S7 method for class +.flatten_df(x) + +## S7 method for class +.flatten_df(x) } \arguments{ \item{x}{(\code{data.frame}, \code{list}, or \code{NULL}) The object to flatten.} diff --git a/man/dot-flatten_df_data_frame.Rd b/man/dot-flatten_df_data_frame.Rd deleted file mode 100644 index d043df4..0000000 --- a/man/dot-flatten_df_data_frame.Rd +++ /dev/null @@ -1,18 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utils.R -\name{.flatten_df_data_frame} -\alias{.flatten_df_data_frame} -\title{Flatten a data frame method} -\usage{ -.flatten_df_data_frame(x) -} -\arguments{ -\item{x}{(\code{data.frame}) The object to return unchanged.} -} -\value{ -A \code{data.frame}. -} -\description{ -Flatten a data frame method -} -\keyword{internal} diff --git a/man/dot-flatten_df_list.Rd b/man/dot-flatten_df_list.Rd deleted file mode 100644 index 588c74b..0000000 --- a/man/dot-flatten_df_list.Rd +++ /dev/null @@ -1,18 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utils.R -\name{.flatten_df_list} -\alias{.flatten_df_list} -\title{Flatten a list method} -\usage{ -.flatten_df_list(x) -} -\arguments{ -\item{x}{(\code{list}) The objects to row-bind.} -} -\value{ -A \code{data.frame}. -} -\description{ -Flatten a list method -} -\keyword{internal} diff --git a/man/dot-flatten_df_null.Rd b/man/dot-flatten_df_null.Rd deleted file mode 100644 index 3fec3b5..0000000 --- a/man/dot-flatten_df_null.Rd +++ /dev/null @@ -1,18 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utils.R -\name{.flatten_df_null} -\alias{.flatten_df_null} -\title{Flatten a \code{NULL} method} -\usage{ -.flatten_df_null(x) -} -\arguments{ -\item{x}{(\code{NULL}) The object to convert.} -} -\value{ -A \code{data.frame}. -} -\description{ -Flatten a \code{NULL} method -} -\keyword{internal} diff --git a/man/dot-generate_pagination.Rd b/man/dot-generate_pagination.Rd index e61234a..9fd955d 100644 --- a/man/dot-generate_pagination.Rd +++ b/man/dot-generate_pagination.Rd @@ -7,7 +7,7 @@ .generate_pagination() } \value{ -An empty \code{list}. +A \code{list} of pagination metadata used while generating path files. } \description{ Generate pagination files diff --git a/man/dot-generate_security_arg_help.Rd b/man/dot-generate_security_arg_help.Rd index 4c9d63f..7fb6ad6 100644 --- a/man/dot-generate_security_arg_help.Rd +++ b/man/dot-generate_security_arg_help.Rd @@ -11,7 +11,7 @@ metadata.} \item{security_args}{(\code{character}) Security argument names to remove from -operation parameters.} +operation parameters (because they are defined once, separately).} } \value{ A \code{list} of template-ready parameter help entries. diff --git a/man/dot-generate_security_signature.Rd b/man/dot-generate_security_signature.Rd index de37450..ec9fa1e 100644 --- a/man/dot-generate_security_signature.Rd +++ b/man/dot-generate_security_signature.Rd @@ -8,7 +8,8 @@ } \arguments{ \item{security_arg_names}{(\code{character}) Security argument names to exclude -from generated operation signatures.} +from generated operation signatures (because they are defined once, +separately).} \item{api_abbr}{(\code{character(1)}) A short (about 2-5 letter) abbreviation for the API, for use in function names and environment variables.} diff --git a/man/dot-is_pkg.Rd b/man/dot-is_pkg.Rd index c9eaccc..bc5220c 100644 --- a/man/dot-is_pkg.Rd +++ b/man/dot-is_pkg.Rd @@ -4,10 +4,7 @@ \alias{.is_pkg} \title{Check whether we're in a package} \usage{ -.is_pkg(base_path = usethis::proj_get()) -} -\arguments{ -\item{base_path}{The root URL of the current project.} +.is_pkg(pkg_dir = usethis::proj_get()) } \value{ \code{TRUE} if the project is a package, \code{FALSE} if not. diff --git a/man/dot-onLoad.Rd b/man/dot-onLoad.Rd deleted file mode 100644 index 4f08f41..0000000 --- a/man/dot-onLoad.Rd +++ /dev/null @@ -1,18 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/zzz.R -\name{.onLoad} -\alias{.onLoad} -\title{Register package methods on load} -\usage{ -.onLoad(...) -} -\arguments{ -\item{...}{Additional arguments passed by R during package loading.} -} -\value{ -\code{NULL} (invisibly). -} -\description{ -Register package methods on load -} -\keyword{internal} diff --git a/man/dot-param_schema_to_r.Rd b/man/dot-param_schema_to_r.Rd index 50b5af9..c76b4ec 100644 --- a/man/dot-param_schema_to_r.Rd +++ b/man/dot-param_schema_to_r.Rd @@ -7,8 +7,7 @@ .param_schema_to_r(params_schema) } \arguments{ -\item{params_schema}{(\code{data.frame}) Schema metadata for operation -parameters.} +\item{params_schema}{(\code{data.frame}) Schema metadata for operation parameters.} } \value{ (\code{character}) Coercion helper names. diff --git a/man/dot-path_row_to_list.Rd b/man/dot-path_row_to_list.Rd index 7c070b2..adb0e92 100644 --- a/man/dot-path_row_to_list.Rd +++ b/man/dot-path_row_to_list.Rd @@ -27,7 +27,7 @@ generated file names.} \item{operation_description}{(\code{character(1)}) The operation description.} -\item{tags}{(\code{character(1)}) The operation tag.} +\item{tags}{(\code{character} or \code{list}) Tags for all operations.} \item{parameters}{(\code{data.frame}) Operation parameters.} diff --git a/man/dot-paths_fill_tags.Rd b/man/dot-paths_fill_tags.Rd index 00fb27e..cb6a26f 100644 --- a/man/dot-paths_fill_tags.Rd +++ b/man/dot-paths_fill_tags.Rd @@ -7,7 +7,7 @@ .paths_fill_tags(tags) } \arguments{ -\item{tags}{(\code{list}) Operation tags from the API definition.} +\item{tags}{(\code{character} or \code{list}) Tags for all operations.} } \value{ (\code{character}) Snake-case tag names. diff --git a/man/dot-paths_need_stbl.Rd b/man/dot-paths_need_stbl.Rd index fe60136..5d02c81 100644 --- a/man/dot-paths_need_stbl.Rd +++ b/man/dot-paths_need_stbl.Rd @@ -10,7 +10,8 @@ \item{paths}{(\code{rapid::class_paths}) API path definitions.} \item{security_arg_names}{(\code{character}) Security argument names to exclude -from generated operation signatures.} +from generated operation signatures (because they are defined once, +separately).} } \value{ (\code{logical(1)}) \code{TRUE} if any path needs \code{stbl}. diff --git a/man/dot-prep_param_args.Rd b/man/dot-prep_param_args.Rd index f624ad7..37a5660 100644 --- a/man/dot-prep_param_args.Rd +++ b/man/dot-prep_param_args.Rd @@ -10,7 +10,7 @@ \item{params}{(\code{list}) Parameter metadata for a single operation.} \item{security_args}{(\code{character}) Security argument names to remove from -operation parameters.} +operation parameters (because they are defined once, separately).} } \value{ (\code{character(1)}) A comma-separated named-argument string. diff --git a/man/dot-remove_security_args.Rd b/man/dot-remove_security_args.Rd index 1e7bb29..814b459 100644 --- a/man/dot-remove_security_args.Rd +++ b/man/dot-remove_security_args.Rd @@ -10,7 +10,7 @@ \item{params}{(\code{list}) Parameter metadata for a single operation.} \item{security_args}{(\code{character}) Security argument names to remove from -operation parameters.} +operation parameters (because they are defined once, separately).} } \value{ A \code{list} of non-security parameters. diff --git a/man/dot-shared-params.Rd b/man/dot-shared-params.Rd index a61b0e5..3193049 100644 --- a/man/dot-shared-params.Rd +++ b/man/dot-shared-params.Rd @@ -4,6 +4,8 @@ \alias{.shared-params} \title{Shared parameters} \arguments{ +\item{addition}{(\code{character}) Text to append when \code{test} is \code{TRUE}.} + \item{allow_empty}{(\code{logical}) Whether empty parameter values may be represented as \code{NULL}.} @@ -16,6 +18,11 @@ package code from.} \item{api_title}{(\code{character(1)}) The API title used in generated package files.} +\item{base_path}{The root URL of the current project.} + +\item{base_url}{(\code{character(1)}) The base URL used in generated test +helpers.} + \item{call}{(\code{environment}) The caller environment for error messages.} \item{config}{(\code{list}) Package-generation configuration data.} @@ -28,28 +35,56 @@ config file.} \item{dir}{(\code{character(1)}) The directory where a generated file should be written.} +\item{endpoint}{(\code{character(1)}) The operation endpoint.} + \item{endpoints}{(\code{character}) Endpoint paths paired with operations.} +\item{filter_in}{(\code{character(1)}) The parameter location to keep.} + +\item{include_stbl}{(\code{logical(1)}) Whether to add \code{stbl} to Imports.} + \item{methods}{(\code{character}) HTTP methods paired with endpoints.} +\item{operation}{(\code{character(1)}) The HTTP method.} + +\item{operation_description}{(\code{character(1)}) The operation description.} + +\item{operation_descriptions}{(\code{character}) Operation descriptions from the +API definition.} + \item{operation_id}{(\code{character(1)}) The operation identifier used in generated file names.} +\item{operation_ids}{(\code{character}) Operation identifiers from the API +definition.} + \item{operation_summaries}{(\code{character}) Operation summaries from the API definition.} +\item{operation_summary}{(\code{character(1)}) The operation summary.} + +\item{original}{(\code{character}) The original text.} + \item{pagination_data}{(\code{list}) Pagination metadata used while generating path files.} +\item{parameters}{(\code{data.frame}) Operation parameters.} + \item{params}{(\code{list}) Parameter metadata for a single operation.} \item{params_df}{(\code{data.frame}) Parameter metadata in tabular form.} -\item{params_schema}{(\code{data.frame}) Schema metadata for operation -parameters.} +\item{params_schema}{(\code{data.frame}) Schema metadata for operation parameters.} + +\item{path}{(\code{character(1)}) The path template.} + +\item{path_operation}{(\code{list}) Template data for one operation.} \item{paths}{(\code{rapid::class_paths}) API path definitions.} +\item{paths_by_operation}{(\code{list}) Template-ready operations keyed by +operation identifier.} + \item{pkg_dir}{(\code{character(1)} or \code{fs_path}) The directory containing package files.} @@ -58,11 +93,16 @@ definition (rapid) file.} \item{required}{(\code{logical}) Whether each parameter is required.} +\item{security_arg_description}{(\code{character(1)}) The argument description.} + +\item{security_arg_name}{(\code{character(1)}) The argument name.} + \item{security_arg_names}{(\code{character}) Security argument names to exclude -from generated operation signatures.} +from generated operation signatures (because they are defined once, +separately).} \item{security_args}{(\code{character}) Security argument names to remove from -operation parameters.} +operation parameters (because they are defined once, separately).} \item{security_data}{(\code{list}) Generated security metadata.} @@ -72,14 +112,35 @@ metadata.} \item{security_scheme_description}{(\code{character(1)}) A security scheme description from the API definition.} +\item{security_scheme_details}{(\code{rapid::class_security_scheme_details}) The +security scheme details.} + +\item{security_scheme_name}{(\code{character(1)}) The security scheme name.} + +\item{security_scheme_type}{(\code{character(1)}) The security scheme type.} + \item{security_schemes}{(\code{rapid::class_security_schemes}) Security schemes from the API definition.} +\item{tag_operations}{(\code{list}) Operations grouped under one tag.} + +\item{tag_name}{(\code{character(1)}) The tag name.} + +\item{tags}{(\code{character} or \code{list}) Tags for all operations.} + \item{target}{(\code{character(1)}) The name of the generated file.} \item{template}{(\code{character(1)}) The template file name to render.} +\item{test}{(\code{logical}) A condition for each element of \code{original}.} + \item{to_collapse}{(\code{character}) The character vector to collapse.} + +\item{type}{(\code{data.frame}) Joined parameter type metadata.} + +\item{x}{(\code{any}) The object to check or coerce.} + +\item{y}{(\code{any}) The default value.} } \description{ These parameters are used in multiple functions. They are defined here to diff --git a/man/op-lengthless-default.Rd b/man/op-lengthless-default.Rd index 8091178..ccab4a5 100644 --- a/man/op-lengthless-default.Rd +++ b/man/op-lengthless-default.Rd @@ -8,9 +8,9 @@ x \%|0|\% y } \arguments{ -\item{x}{(\code{any}) Object to check.} +\item{x}{(\code{any}) The object to check or coerce.} -\item{y}{(\code{any}) Default value for \code{x}.} +\item{y}{(\code{any}) The default value.} } \value{ If \code{!length(x)}, will return \code{x}; otherwise returns \code{y}. diff --git a/man/op-na-coalesce.Rd b/man/op-na-coalesce.Rd index f64e065..84438e7 100644 --- a/man/op-na-coalesce.Rd +++ b/man/op-na-coalesce.Rd @@ -8,7 +8,7 @@ x \%|\% y } \arguments{ -\item{x}{(\code{any}) A vector that may contain \code{NA} elements.} +\item{x}{(\code{any}) The object to check or coerce.} \item{y}{(\code{any}, coercible to the same class as \code{x}) A value or vector to replace \code{NA} elements in \code{x}. Will be recycled to the same length as \code{x}.} diff --git a/man/op-no-char-default.Rd b/man/op-no-char-default.Rd index 03f015e..2850b73 100644 --- a/man/op-no-char-default.Rd +++ b/man/op-no-char-default.Rd @@ -8,9 +8,9 @@ x \%|a|\% y } \arguments{ -\item{x}{(\code{any}) Object to check.} +\item{x}{(\code{any}) The object to check or coerce.} -\item{y}{(\code{character}) Default value for \code{x}.} +\item{y}{(\code{character}) The default value.} } \value{ If \code{!nzchar(x)}, will return \code{y}; otherwise returns \code{x}. diff --git a/man/op-null-continuation.Rd b/man/op-null-continuation.Rd index 1b1e0f0..c47e8a6 100644 --- a/man/op-null-continuation.Rd +++ b/man/op-null-continuation.Rd @@ -8,9 +8,9 @@ x \%&&\% y } \arguments{ -\item{x}{(\code{any}) Object to check.} +\item{x}{(\code{any}) The object to check or coerce.} -\item{y}{(\code{any}) Default value for non-\code{NULL} \code{x}.} +\item{y}{(\code{any}) The default value.} } \value{ If \code{x} is \code{NULL}, will return \code{x}; otherwise returns \code{y}. diff --git a/man/op-null-default.Rd b/man/op-null-default.Rd index fea2a8c..80a2af7 100644 --- a/man/op-null-default.Rd +++ b/man/op-null-default.Rd @@ -8,9 +8,9 @@ x \%||\% y } \arguments{ -\item{x}{(\code{any}) Object to check.} +\item{x}{(\code{any}) The object to check or coerce.} -\item{y}{(\code{any}) Default value for \code{x}.} +\item{y}{(\code{any}) The default value.} } \value{ If \code{x} is \code{NULL}, will return \code{y}; otherwise returns \code{x}. From dfa463e044f3db68c005f24f8caf3df7ce729ab0 Mon Sep 17 00:00:00 2001 From: Jon Harmon Date: Sat, 16 May 2026 16:58:54 -0500 Subject: [PATCH 06/13] Doc dots --- R/utils.R | 1 + man/dot-flatten_df.Rd | 2 ++ 2 files changed, 3 insertions(+) diff --git a/R/utils.R b/R/utils.R index c093c81..7193b8f 100644 --- a/R/utils.R +++ b/R/utils.R @@ -136,6 +136,7 @@ if (exists("%||%", envir = baseenv())) { #' Flatten a data frame or list of data frames #' #' @param x (`data.frame`, `list`, or `NULL`) The object to flatten. +#' @param ... Not used. #' @returns A single `data.frame`. Lists of data frames are flattened with #' [purrr::list_rbind()], and `NULL` values are converted to empty data #' frames. diff --git a/man/dot-flatten_df.Rd b/man/dot-flatten_df.Rd index 50e57a7..3f76388 100644 --- a/man/dot-flatten_df.Rd +++ b/man/dot-flatten_df.Rd @@ -16,6 +16,8 @@ } \arguments{ \item{x}{(\code{data.frame}, \code{list}, or \code{NULL}) The object to flatten.} + +\item{...}{Not used.} } \value{ A single \code{data.frame}. Lists of data frames are flattened with From 144eac39acb6d7b3456b96689783c3e73da71020 Mon Sep 17 00:00:00 2001 From: Jon Harmon Date: Sun, 17 May 2026 06:34:15 -0500 Subject: [PATCH 07/13] Add dots to methods of `.flatten_df()` --- R/utils.R | 6 +++--- man/dot-flatten_df.Rd | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/R/utils.R b/R/utils.R index 7193b8f..cc1befc 100644 --- a/R/utils.R +++ b/R/utils.R @@ -145,10 +145,10 @@ if (exists("%||%", envir = baseenv())) { #' @rdname dot-flatten_df #' @keywords internal -S7::method(.flatten_df, class_data.frame) <- function(x) x +S7::method(.flatten_df, class_data.frame) <- function(x, ...) x #' @rdname dot-flatten_df #' @keywords internal -S7::method(.flatten_df, class_list) <- function(x) purrr::list_rbind(x) +S7::method(.flatten_df, class_list) <- function(x, ...) purrr::list_rbind(x) -S7::method(.flatten_df, NULL) <- function(x) data.frame() +S7::method(.flatten_df, NULL) <- function(x, ...) data.frame() diff --git a/man/dot-flatten_df.Rd b/man/dot-flatten_df.Rd index 3f76388..e9cf939 100644 --- a/man/dot-flatten_df.Rd +++ b/man/dot-flatten_df.Rd @@ -9,10 +9,10 @@ .flatten_df(x, ...) ## S7 method for class -.flatten_df(x) +.flatten_df(x, ...) ## S7 method for class -.flatten_df(x) +.flatten_df(x, ...) } \arguments{ \item{x}{(\code{data.frame}, \code{list}, or \code{NULL}) The object to flatten.} From d797d4e55e47c4450e9f7885db562076b9f85cdf Mon Sep 17 00:00:00 2001 From: Jon Harmon Date: Sun, 17 May 2026 06:35:21 -0500 Subject: [PATCH 08/13] Use rlang wording for dots. --- R/utils.R | 2 +- man/dot-flatten_df.Rd | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/R/utils.R b/R/utils.R index cc1befc..06e82ec 100644 --- a/R/utils.R +++ b/R/utils.R @@ -136,7 +136,7 @@ if (exists("%||%", envir = baseenv())) { #' Flatten a data frame or list of data frames #' #' @param x (`data.frame`, `list`, or `NULL`) The object to flatten. -#' @param ... Not used. +#' @inheritParams rlang::args_dots_empty #' @returns A single `data.frame`. Lists of data frames are flattened with #' [purrr::list_rbind()], and `NULL` values are converted to empty data #' frames. diff --git a/man/dot-flatten_df.Rd b/man/dot-flatten_df.Rd index e9cf939..71fff1e 100644 --- a/man/dot-flatten_df.Rd +++ b/man/dot-flatten_df.Rd @@ -17,7 +17,7 @@ \arguments{ \item{x}{(\code{data.frame}, \code{list}, or \code{NULL}) The object to flatten.} -\item{...}{Not used.} +\item{...}{These dots are for future extensions and must be empty.} } \value{ A single \code{data.frame}. Lists of data frames are flattened with From 009ea7cadca727f99f5620766eea10927febbb5b Mon Sep 17 00:00:00 2001 From: Jon Harmon Date: Sun, 17 May 2026 06:50:20 -0500 Subject: [PATCH 09/13] Standardize return style. --- .github/skills/document/SKILL.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/.github/skills/document/SKILL.md b/.github/skills/document/SKILL.md index 9914cdd..07a3321 100644 --- a/.github/skills/document/SKILL.md +++ b/.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, ...) { ... } ``` From 3828a75c0df4dd44f4f95bd6cccfba24fe4e2122 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 17 May 2026 11:56:40 +0000 Subject: [PATCH 10/13] Standardize return style Agent-Logs-Url: https://github.com/api2r/beekeeper/sessions/5f5b15a2-1ceb-4b78-859c-c11f3c6ba44c Co-authored-by: jonthegeek <33983824+jonthegeek@users.noreply.github.com> --- R/aaa-conditions.R | 6 ++-- R/as_bk_data.R | 2 +- R/generate_pkg-pagination.R | 2 +- R/generate_pkg-paths.R | 19 +++++++------ R/generate_pkg-prepare.R | 2 +- R/generate_pkg-security.R | 14 +++++----- R/generate_pkg-setup.R | 12 ++++---- R/generate_pkg-template.R | 3 +- R/generate_pkg.R | 5 ++-- R/use_beekeeper.R | 7 +++-- R/utils.R | 28 +++++++++---------- man/as_bk_data.Rd | 2 +- man/dot-assert_is_pkg.Rd | 2 +- man/dot-bk_use_template.Rd | 3 +- man/dot-collapse_comma.Rd | 2 +- man/dot-collapse_comma_newline.Rd | 2 +- man/dot-collapse_comma_self_equal.Rd | 2 +- man/dot-collapse_quote_comma.Rd | 2 +- man/dot-flatten_df.Rd | 6 ++-- man/dot-flatten_params_df.Rd | 2 +- man/dot-generate_pagination.Rd | 2 +- man/dot-generate_paths.Rd | 2 +- man/dot-generate_paths_files.Rd | 2 +- man/dot-generate_pkg_impl.Rd | 2 +- man/dot-generate_prepare.Rd | 2 +- man/dot-generate_security.Rd | 2 +- man/dot-generate_security_arg_help.Rd | 2 +- man/dot-glue_pipe_brace.Rd | 2 +- man/dot-is_pkg.Rd | 2 +- man/dot-params_to_list.Rd | 2 +- man/dot-params_to_validations.Rd | 2 +- man/dot-path_row_to_list.Rd | 2 +- man/dot-paths_to_clean_df.Rd | 3 +- man/dot-pkg_abort.Rd | 2 +- man/dot-pkg_inform.Rd | 2 +- man/dot-pkg_warn.Rd | 2 +- man/dot-prepare_params_df.Rd | 2 +- man/dot-remove_security_args.Rd | 2 +- man/dot-security_arg_description_clean.Rd | 2 +- man/dot-security_args_compile.Rd | 2 +- ...dot-security_scheme_collection_finalize.Rd | 2 +- man/dot-security_scheme_rotate.Rd | 2 +- man/dot-security_schemes_collect.Rd | 2 +- man/dot-setup_r.Rd | 2 +- man/dot-stabilize_config.Rd | 2 +- man/generate_pkg.Rd | 3 +- man/op-lengthless-default.Rd | 2 +- man/op-na-coalesce.Rd | 4 +-- man/op-no-char-default.Rd | 2 +- man/op-null-continuation.Rd | 2 +- man/op-null-default.Rd | 2 +- man/read_api_definition.Rd | 2 +- man/read_config.Rd | 2 +- man/use_beekeeper.Rd | 7 +++-- 54 files changed, 102 insertions(+), 98 deletions(-) diff --git a/R/aaa-conditions.R b/R/aaa-conditions.R index 4ce7af5..9ae5645 100644 --- a/R/aaa-conditions.R +++ b/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, diff --git a/R/as_bk_data.R b/R/as_bk_data.R index 72b964f..f57223b 100644 --- a/R/as_bk_data.R +++ b/R/as_bk_data.R @@ -4,7 +4,7 @@ #' #' @inheritParams .shared-params #' @inheritParams rlang::args_dots_empty -#' @returns A list. +#' @returns (`list`) A list. #' @keywords internal as_bk_data <- S7::new_generic("as_bk_data", dispatch_args = "x") diff --git a/R/generate_pkg-pagination.R b/R/generate_pkg-pagination.R index 5b03b05..d24d681 100644 --- a/R/generate_pkg-pagination.R +++ b/R/generate_pkg-pagination.R @@ -1,6 +1,6 @@ #' Generate pagination files #' -#' @returns A `list` of pagination metadata used while generating path 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) diff --git a/R/generate_pkg-paths.R b/R/generate_pkg-paths.R index fdad49b..d08c9af 100644 --- a/R/generate_pkg-paths.R +++ b/R/generate_pkg-paths.R @@ -1,7 +1,7 @@ #' Generate files for API paths #' #' @inheritParams .shared-params -#' @returns A `character` vector of generated file paths. +#' @returns (`character`) Generated file paths. #' @keywords internal .generate_paths <- function( paths, @@ -46,7 +46,8 @@ S7::method(as_bk_data, class_paths) <- function(x, ...) { #' Convert API paths to an operations data frame #' #' @inheritParams .shared-params -#' @returns A [tibble::tibble()] with one row per non-deprecated operation. +#' @returns (`tibble`) A [tibble::tibble()] with one row per non-deprecated +#' operation. #' @keywords internal .paths_to_clean_df <- function(paths) { operations_df <- tibble::as_tibble(paths) |> @@ -137,7 +138,7 @@ S7::method(as_bk_data, class_paths) <- function(x, ...) { #' #' @param ... Additional columns, ignored. #' @inheritParams .shared-params -#' @returns A `list` describing one operation. +#' @returns (`list`) One operation description. #' @keywords internal .path_row_to_list <- function( operation_id, @@ -166,7 +167,7 @@ S7::method(as_bk_data, class_paths) <- function(x, ...) { #' Prepare parameter metadata #' #' @inheritParams .shared-params -#' @returns A `data.frame` of prepared parameter metadata. +#' @returns (`data.frame`) Prepared parameter metadata. #' @keywords internal .prepare_params_df <- function(params_df) { params_df <- .flatten_params_df(params_df) @@ -190,7 +191,7 @@ S7::method(as_bk_data, class_paths) <- function(x, ...) { #' Flatten parameter metadata #' #' @inheritParams .shared-params -#' @returns A `data.frame` of flattened parameter metadata. +#' @returns (`data.frame`) Flattened parameter metadata. #' @keywords internal .flatten_params_df <- function(params_df) { params_df <- .flatten_df(params_df) @@ -203,7 +204,7 @@ S7::method(as_bk_data, class_paths) <- function(x, ...) { #' Convert parameter rows to a list #' #' @inheritParams .shared-params -#' @returns A `list` of parameter metadata entries. +#' @returns (`list`) Parameter metadata entries. #' @keywords internal .params_to_list <- function(params_df) { if (!nrow(params_df)) { @@ -312,7 +313,7 @@ S7::method(as_bk_data, class_paths) <- function(x, ...) { #' Generate files for all operations #' #' @inheritParams .shared-params -#' @returns A `character` vector of generated file paths. +#' @returns (`character`) Generated file paths. #' @keywords internal .generate_paths_files <- function( paths_by_operation, @@ -384,7 +385,7 @@ S7::method(as_bk_data, class_paths) <- function(x, ...) { #' Remove security parameters #' #' @inheritParams .shared-params -#' @returns A `list` of non-security parameters. +#' @returns (`list`) Non-security parameters. #' @keywords internal .remove_security_args <- function(params, security_args) { purrr::discard( @@ -407,7 +408,7 @@ S7::method(as_bk_data, class_paths) <- function(x, ...) { #' Convert parameters to validation metadata #' #' @inheritParams .shared-params -#' @returns A `list` of validation metadata. +#' @returns (`list`) Validation metadata. #' @keywords internal .params_to_validations <- function(params) { checks <- purrr::keep( diff --git a/R/generate_pkg-prepare.R b/R/generate_pkg-prepare.R index 7ed1068..24dddb9 100644 --- a/R/generate_pkg-prepare.R +++ b/R/generate_pkg-prepare.R @@ -1,7 +1,7 @@ #' Generate prepare files #' #' @inheritParams .shared-params -#' @returns A `character` vector of generated file paths. +#' @returns (`character`) Generated file paths. #' @keywords internal .generate_prepare <- function(config, api_definition, security_data) { c( diff --git a/R/generate_pkg-security.R b/R/generate_pkg-security.R index 5043e1c..c872edd 100644 --- a/R/generate_pkg-security.R +++ b/R/generate_pkg-security.R @@ -1,7 +1,7 @@ #' Generate security files and metadata #' #' @inheritParams .shared-params -#' @returns A `list` of generated security metadata. +#' @returns (`list`) Generated security metadata. #' @keywords internal .generate_security <- function(api_abbr, security_schemes) { security_data <- as_bk_data(security_schemes) @@ -45,7 +45,7 @@ S7::method(as_bk_data, class_security_schemes) <- function(x, ...) { #' Collect security scheme metadata #' #' @inheritParams .shared-params -#' @returns A `list` of security scheme metadata. +#' @returns (`list`) Security scheme metadata. #' @keywords internal .security_schemes_collect <- function(security_schemes) { purrr::pmap( @@ -62,7 +62,7 @@ S7::method(as_bk_data, class_security_schemes) <- function(x, ...) { #' Convert one security scheme to a list #' #' @inheritParams .shared-params -#' @returns A `list` describing one security scheme. +#' @returns (`list`) One security scheme description. #' @keywords internal .security_scheme_rotate <- function( security_scheme_name, @@ -113,7 +113,7 @@ S7::method(as_bk_data, class_security_schemes) <- function(x, ...) { #' Finalize collected security scheme data #' #' @inheritParams .shared-params -#' @returns A `list` of finalized security metadata. +#' @returns (`list`) Finalized security metadata. #' @keywords internal .security_scheme_collection_finalize <- function(security_scheme_collection) { security_scheme_data <- c( @@ -129,7 +129,7 @@ S7::method(as_bk_data, class_security_schemes) <- function(x, ...) { #' Compile security argument metadata #' #' @inheritParams .shared-params -#' @returns A `list` of compiled security argument values. +#' @returns (`list`) Compiled security argument values. #' @keywords internal .security_args_compile <- function(security_scheme_collection) { security_args <- sort(unique(purrr::map_chr( @@ -152,7 +152,7 @@ S7::method(as_bk_data, class_security_schemes) <- function(x, ...) { #' Build security argument help entries #' #' @inheritParams .shared-params -#' @returns A `list` of template-ready parameter help entries. +#' @returns (`list`) Template-ready parameter help entries. #' @keywords internal .generate_security_arg_help <- function( security_scheme_collection, @@ -175,7 +175,7 @@ S7::method(as_bk_data, class_security_schemes) <- function(x, ...) { #' Format one security argument help entry #' #' @inheritParams .shared-params -#' @returns A named `list` with `name` and `description`. +#' @returns (`list`) A named list with `name` and `description`. #' @keywords internal .security_arg_description_clean <- function( security_arg_description, diff --git a/R/generate_pkg-setup.R b/R/generate_pkg-setup.R index 5c479f2..925ec0b 100644 --- a/R/generate_pkg-setup.R +++ b/R/generate_pkg-setup.R @@ -2,7 +2,7 @@ #' #' @inheritParams .is_pkg #' -#' @returns `NULL`, invisibly. +#' @returns (`NULL`, invisibly) Called for error side effect. #' @keywords internal .assert_is_pkg <- function(pkg_dir = usethis::proj_get()) { if (.is_pkg(pkg_dir)) { @@ -18,7 +18,7 @@ #' #' Inspired by usethis:::is_package. #' -#' @returns `TRUE` if the project is a package, `FALSE` if not. +#' @returns (`logical(1)`) `TRUE` if the project is a package, `FALSE` if not. #' @keywords internal .is_pkg <- function(pkg_dir = usethis::proj_get()) { root_file <- rlang::try_fetch( @@ -49,7 +49,7 @@ #' last updated, in the format "YYYY-MM-DD HH:MM:SS" (UTC). #' #' @inheritParams .shared-params -#' @returns A `list` of configuration information, with elements `api_title`, +#' @returns (`list`) Configuration information, with elements `api_title`, #' `api_abbr`, `api_version`, `rapid_file`, and `updated_on`. #' @export read_config <- function(pkg_dir = ".", config_file = "_beekeeper.yml") { @@ -60,7 +60,7 @@ read_config <- function(pkg_dir = ".", config_file = "_beekeeper.yml") { #' Stabilize beekeeper config values #' #' @inheritParams .shared-params -#' @returns A stabilized `list`. +#' @returns (`list`) A stabilized config list. #' @keywords internal .stabilize_config <- function(config) { config$api_title <- stbl::stabilize_character_scalar(config$api_title) @@ -86,7 +86,7 @@ read_config <- function(pkg_dir = ".", config_file = "_beekeeper.yml") { #' by [use_beekeeper()] based on an OpenAPI definition file. #' #' @inheritParams .shared-params -#' @returns A [rapid::class_rapid()] with the definition of the API. +#' @returns (`rapid::class_rapid`) The definition of the API. #' @export read_api_definition <- function( pkg_dir = ".", @@ -98,7 +98,7 @@ read_api_definition <- function( #' Set up package directories and dependencies #' #' @inheritParams .shared-params -#' @returns `NULL` (invisibly). +#' @returns (`NULL`, invisibly) Called for setup side effects. #' @keywords internal .setup_r <- function(pkg_dir, include_stbl = FALSE) { if (as.character(pkg_dir) != ".") { diff --git a/R/generate_pkg-template.R b/R/generate_pkg-template.R index b769d6f..bd6ace4 100644 --- a/R/generate_pkg-template.R +++ b/R/generate_pkg-template.R @@ -2,7 +2,8 @@ #' #' @inheritParams .shared-params #' @inheritParams rlang::args_dots_empty -#' @returns The path to the generated or updated file, invisibly. +#' @returns (`character(1)`, invisibly) The path to the generated or updated +#' file. #' @keywords internal .bk_use_template <- function( template, diff --git a/R/generate_pkg.R b/R/generate_pkg.R index 9654c24..42ffb63 100644 --- a/R/generate_pkg.R +++ b/R/generate_pkg.R @@ -6,8 +6,7 @@ #' #' @inheritParams .shared-params #' -#' @returns A character vector of paths to files that were added or updated, -#' invisibly. +#' @returns (`character`, invisibly) Paths to files that were added or updated. #' @export generate_pkg <- function( api_abbr = NULL, @@ -44,7 +43,7 @@ generate_pkg <- function( #' Generate package files from prepared inputs #' #' @inheritParams .shared-params -#' @returns A `character` vector of generated file paths, invisibly. +#' @returns (`character`, invisibly) Generated file paths. #' @keywords internal .generate_pkg_impl <- function(config, api_definition, security_data) { prep_files <- .generate_prepare(config, api_definition, security_data) diff --git a/R/use_beekeeper.R b/R/use_beekeeper.R index 27ab82f..1fd04c7 100644 --- a/R/use_beekeeper.R +++ b/R/use_beekeeper.R @@ -11,9 +11,10 @@ #' generated by reading such a document. #' @inheritParams .shared-params #' -#' @returns The path to the configuration file, invisibly. The config file is -#' written as a side effect of this function. The rapid object is also -#' written, and the path to that file is saved in the config file. +#' @returns (`character(1)`, invisibly) The path to the configuration file. +#' The config file is written as a side effect of this function. The rapid +#' object is also written, and the path to that file is saved in the config +#' file. #' @export use_beekeeper <- function( x, diff --git a/R/utils.R b/R/utils.R index 06e82ec..df5ab67 100644 --- a/R/utils.R +++ b/R/utils.R @@ -1,7 +1,7 @@ #' Default value for `NULL` #' #' @inheritParams .shared-params -#' @returns If `x` is `NULL`, will return `y`; otherwise returns `x`. +#' @returns (`any`) If `x` is `NULL`, returns `y`; otherwise returns `x`. #' @name op-null-default #' @family empty operators #' @keywords internal @@ -17,7 +17,7 @@ if (exists("%||%", envir = baseenv())) { #' Default value for non-`NULL` #' #' @inheritParams .shared-params -#' @returns If `x` is `NULL`, will return `x`; otherwise returns `y`. +#' @returns (`any`) If `x` is `NULL`, returns `x`; otherwise returns `y`. #' @name op-null-continuation #' @family empty operators #' @keywords internal @@ -28,7 +28,7 @@ if (exists("%||%", envir = baseenv())) { #' Default value for length 0 #' #' @inheritParams .shared-params -#' @returns If `!length(x)`, will return `x`; otherwise returns `y`. +#' @returns (`any`) If `!length(x)`, returns `x`; otherwise returns `y`. #' @keywords internal #' @name op-lengthless-default #' @family empty operators @@ -41,7 +41,7 @@ if (exists("%||%", envir = baseenv())) { #' #' @param y (`character`) The default value. #' @inheritParams .shared-params -#' @returns If `!nzchar(x)`, will return `y`; otherwise returns `x`. +#' @returns (`character`) If `!nzchar(x)`, returns `y`; otherwise returns `x`. #' @keywords internal #' @name op-no-char-default #' @family empty operators @@ -59,8 +59,8 @@ if (exists("%||%", envir = baseenv())) { #' @param y (`any`, coercible to the same class as `x`) A value or vector to #' replace `NA` elements in `x`. Will be recycled to the same length as `x`. #' @inheritParams .shared-params -#' @returns A vector of the same length as `x`, where each `NA` element in `x` -#' is replaced by the corresponding element in `y`. +#' @returns (`vector`) A vector of the same length as `x`, where each `NA` +#' element in `x` is replaced by the corresponding element in `y`. #' @keywords internal #' @name op-na-coalesce #' @family empty operators @@ -72,7 +72,7 @@ if (exists("%||%", envir = baseenv())) { #' Collapse to a comma-separated string #' #' @inheritParams .shared-params -#' @returns A length-1, comma-separated glue object. +#' @returns (`glue`) A length-1, comma-separated glue object. #' @keywords internal .collapse_comma <- function(to_collapse) { glue::glue_collapse(to_collapse, sep = ", ") @@ -81,7 +81,7 @@ if (exists("%||%", envir = baseenv())) { #' Collapse to a comma-separated vertical string #' #' @inheritParams .shared-params -#' @returns A length-1, comma-separated glue object with newlines. +#' @returns (`glue`) A length-1, comma-separated glue object with newlines. #' @keywords internal .collapse_comma_newline <- function(to_collapse) { glue::glue_collapse(to_collapse, sep = ",\n") @@ -90,7 +90,7 @@ if (exists("%||%", envir = baseenv())) { #' Collapse to a comma-separated quoted string #' #' @inheritParams .shared-params -#' @returns A length-1, comma-separated glue object. +#' @returns (`glue`) A length-1, comma-separated glue object. #' @keywords internal .collapse_quote_comma <- function(to_collapse) { stringr::str_flatten_comma(paste0('"', to_collapse, '"')) @@ -99,7 +99,7 @@ if (exists("%||%", envir = baseenv())) { #' Collapse to a comma-separated x = x string #' #' @inheritParams .shared-params -#' @returns A length-1, comma-separated glue object. +#' @returns (`glue`) A length-1, comma-separated glue object. #' @keywords internal .collapse_comma_self_equal <- function(to_collapse) { .collapse_comma(glue::glue("{to_collapse} = {to_collapse}")) @@ -118,7 +118,7 @@ if (exists("%||%", envir = baseenv())) { #' #' @param ... Expressions passed to [glue::glue()]. #' @param .envir (`environment`) The environment in which to evaluate `...`. -#' @returns A glue object. +#' @returns (`glue`) A glue object. #' @keywords internal .glue_pipe_brace <- function(..., .envir = rlang::caller_env()) { glue::glue(..., .open = "|{", .close = "}|", .envir = .envir) @@ -137,9 +137,9 @@ if (exists("%||%", envir = baseenv())) { #' #' @param x (`data.frame`, `list`, or `NULL`) The object to flatten. #' @inheritParams rlang::args_dots_empty -#' @returns A single `data.frame`. Lists of data frames are flattened with -#' [purrr::list_rbind()], and `NULL` values are converted to empty data -#' frames. +#' @returns (`data.frame`) A single data frame. Lists of data frames are +#' flattened with [purrr::list_rbind()], and `NULL` values are converted to +#' empty data frames. #' @keywords internal .flatten_df <- S7::new_generic(".flatten_df", dispatch_args = "x") diff --git a/man/as_bk_data.Rd b/man/as_bk_data.Rd index 40f2a8e..36a56bd 100644 --- a/man/as_bk_data.Rd +++ b/man/as_bk_data.Rd @@ -33,7 +33,7 @@ as_bk_data(x, ...) \item{...}{These dots are for future extensions and must be empty.} } \value{ -A list. +(\code{list}) A list. } \description{ Convert \code{rapid} objects to lists of properties to use in beekeeper templates. diff --git a/man/dot-assert_is_pkg.Rd b/man/dot-assert_is_pkg.Rd index f8986b8..2bf5911 100644 --- a/man/dot-assert_is_pkg.Rd +++ b/man/dot-assert_is_pkg.Rd @@ -7,7 +7,7 @@ .assert_is_pkg(pkg_dir = usethis::proj_get()) } \value{ -\code{NULL}, invisibly. +(\code{NULL}, invisibly) Called for error side effect. } \description{ Error if not in package diff --git a/man/dot-bk_use_template.Rd b/man/dot-bk_use_template.Rd index 3b166c9..48bae24 100644 --- a/man/dot-bk_use_template.Rd +++ b/man/dot-bk_use_template.Rd @@ -25,7 +25,8 @@ written.} } \value{ -The path to the generated or updated file, invisibly. +(\code{character(1)}, invisibly) The path to the generated or updated +file. } \description{ Use a template in this package diff --git a/man/dot-collapse_comma.Rd b/man/dot-collapse_comma.Rd index 4cfed87..dd0ef08 100644 --- a/man/dot-collapse_comma.Rd +++ b/man/dot-collapse_comma.Rd @@ -10,7 +10,7 @@ \item{to_collapse}{(\code{character}) The character vector to collapse.} } \value{ -A length-1, comma-separated glue object. +(\code{glue}) A length-1, comma-separated glue object. } \description{ Collapse to a comma-separated string diff --git a/man/dot-collapse_comma_newline.Rd b/man/dot-collapse_comma_newline.Rd index 88f9634..5c3a380 100644 --- a/man/dot-collapse_comma_newline.Rd +++ b/man/dot-collapse_comma_newline.Rd @@ -10,7 +10,7 @@ \item{to_collapse}{(\code{character}) The character vector to collapse.} } \value{ -A length-1, comma-separated glue object with newlines. +(\code{glue}) A length-1, comma-separated glue object with newlines. } \description{ Collapse to a comma-separated vertical string diff --git a/man/dot-collapse_comma_self_equal.Rd b/man/dot-collapse_comma_self_equal.Rd index 73222fd..063548c 100644 --- a/man/dot-collapse_comma_self_equal.Rd +++ b/man/dot-collapse_comma_self_equal.Rd @@ -10,7 +10,7 @@ \item{to_collapse}{(\code{character}) The character vector to collapse.} } \value{ -A length-1, comma-separated glue object. +(\code{glue}) A length-1, comma-separated glue object. } \description{ Collapse to a comma-separated x = x string diff --git a/man/dot-collapse_quote_comma.Rd b/man/dot-collapse_quote_comma.Rd index 4a10e8c..e6aa0fb 100644 --- a/man/dot-collapse_quote_comma.Rd +++ b/man/dot-collapse_quote_comma.Rd @@ -10,7 +10,7 @@ \item{to_collapse}{(\code{character}) The character vector to collapse.} } \value{ -A length-1, comma-separated glue object. +(\code{glue}) A length-1, comma-separated glue object. } \description{ Collapse to a comma-separated quoted string diff --git a/man/dot-flatten_df.Rd b/man/dot-flatten_df.Rd index 71fff1e..b05aa2a 100644 --- a/man/dot-flatten_df.Rd +++ b/man/dot-flatten_df.Rd @@ -20,9 +20,9 @@ \item{...}{These dots are for future extensions and must be empty.} } \value{ -A single \code{data.frame}. Lists of data frames are flattened with -\code{\link[purrr:list_rbind]{purrr::list_rbind()}}, and \code{NULL} values are converted to empty data -frames. +(\code{data.frame}) A single data frame. Lists of data frames are +flattened with \code{\link[purrr:list_rbind]{purrr::list_rbind()}}, and \code{NULL} values are converted to +empty data frames. } \description{ Flatten a data frame or list of data frames diff --git a/man/dot-flatten_params_df.Rd b/man/dot-flatten_params_df.Rd index 65e32e1..ba3583a 100644 --- a/man/dot-flatten_params_df.Rd +++ b/man/dot-flatten_params_df.Rd @@ -10,7 +10,7 @@ \item{params_df}{(\code{data.frame}) Parameter metadata in tabular form.} } \value{ -A \code{data.frame} of flattened parameter metadata. +(\code{data.frame}) Flattened parameter metadata. } \description{ Flatten parameter metadata diff --git a/man/dot-generate_pagination.Rd b/man/dot-generate_pagination.Rd index 9fd955d..5ec2cd6 100644 --- a/man/dot-generate_pagination.Rd +++ b/man/dot-generate_pagination.Rd @@ -7,7 +7,7 @@ .generate_pagination() } \value{ -A \code{list} of pagination metadata used while generating path files. +(\code{list}) Pagination metadata used while generating path files. } \description{ Generate pagination files diff --git a/man/dot-generate_paths.Rd b/man/dot-generate_paths.Rd index 64dcad7..eb528a1 100644 --- a/man/dot-generate_paths.Rd +++ b/man/dot-generate_paths.Rd @@ -27,7 +27,7 @@ path files.} helpers.} } \value{ -A \code{character} vector of generated file paths. +(\code{character}) Generated file paths. } \description{ Generate files for API paths diff --git a/man/dot-generate_paths_files.Rd b/man/dot-generate_paths_files.Rd index e994d07..29e73d1 100644 --- a/man/dot-generate_paths_files.Rd +++ b/man/dot-generate_paths_files.Rd @@ -24,7 +24,7 @@ the API, for use in function names and environment variables.} path files.} } \value{ -A \code{character} vector of generated file paths. +(\code{character}) Generated file paths. } \description{ Generate files for all operations diff --git a/man/dot-generate_pkg_impl.Rd b/man/dot-generate_pkg_impl.Rd index fcb84df..90bae1b 100644 --- a/man/dot-generate_pkg_impl.Rd +++ b/man/dot-generate_pkg_impl.Rd @@ -15,7 +15,7 @@ package code from.} \item{security_data}{(\code{list}) Generated security metadata.} } \value{ -A \code{character} vector of generated file paths, invisibly. +(\code{character}, invisibly) Generated file paths. } \description{ Generate package files from prepared inputs diff --git a/man/dot-generate_prepare.Rd b/man/dot-generate_prepare.Rd index ff38f25..6270c9f 100644 --- a/man/dot-generate_prepare.Rd +++ b/man/dot-generate_prepare.Rd @@ -15,7 +15,7 @@ package code from.} \item{security_data}{(\code{list}) Generated security metadata.} } \value{ -A \code{character} vector of generated file paths. +(\code{character}) Generated file paths. } \description{ Generate prepare files diff --git a/man/dot-generate_security.Rd b/man/dot-generate_security.Rd index e7f0580..13480f5 100644 --- a/man/dot-generate_security.Rd +++ b/man/dot-generate_security.Rd @@ -14,7 +14,7 @@ the API, for use in function names and environment variables.} from the API definition.} } \value{ -A \code{list} of generated security metadata. +(\code{list}) Generated security metadata. } \description{ Generate security files and metadata diff --git a/man/dot-generate_security_arg_help.Rd b/man/dot-generate_security_arg_help.Rd index 7fb6ad6..a9e3026 100644 --- a/man/dot-generate_security_arg_help.Rd +++ b/man/dot-generate_security_arg_help.Rd @@ -14,7 +14,7 @@ metadata.} operation parameters (because they are defined once, separately).} } \value{ -A \code{list} of template-ready parameter help entries. +(\code{list}) Template-ready parameter help entries. } \description{ Build security argument help entries diff --git a/man/dot-glue_pipe_brace.Rd b/man/dot-glue_pipe_brace.Rd index 1411c53..de2a99a 100644 --- a/man/dot-glue_pipe_brace.Rd +++ b/man/dot-glue_pipe_brace.Rd @@ -12,7 +12,7 @@ \item{.envir}{(\code{environment}) The environment in which to evaluate \code{...}.} } \value{ -A glue object. +(\code{glue}) A glue object. } \description{ Interpolate glue with pipe braces diff --git a/man/dot-is_pkg.Rd b/man/dot-is_pkg.Rd index bc5220c..df3b40d 100644 --- a/man/dot-is_pkg.Rd +++ b/man/dot-is_pkg.Rd @@ -7,7 +7,7 @@ .is_pkg(pkg_dir = usethis::proj_get()) } \value{ -\code{TRUE} if the project is a package, \code{FALSE} if not. +(\code{logical(1)}) \code{TRUE} if the project is a package, \code{FALSE} if not. } \description{ Inspired by usethis:::is_package. diff --git a/man/dot-params_to_list.Rd b/man/dot-params_to_list.Rd index 4c7e957..26d8e6e 100644 --- a/man/dot-params_to_list.Rd +++ b/man/dot-params_to_list.Rd @@ -10,7 +10,7 @@ \item{params_df}{(\code{data.frame}) Parameter metadata in tabular form.} } \value{ -A \code{list} of parameter metadata entries. +(\code{list}) Parameter metadata entries. } \description{ Convert parameter rows to a list diff --git a/man/dot-params_to_validations.Rd b/man/dot-params_to_validations.Rd index f512bb7..11a951e 100644 --- a/man/dot-params_to_validations.Rd +++ b/man/dot-params_to_validations.Rd @@ -10,7 +10,7 @@ \item{params}{(\code{list}) Parameter metadata for a single operation.} } \value{ -A \code{list} of validation metadata. +(\code{list}) Validation metadata. } \description{ Convert parameters to validation metadata diff --git a/man/dot-path_row_to_list.Rd b/man/dot-path_row_to_list.Rd index adb0e92..67cb21b 100644 --- a/man/dot-path_row_to_list.Rd +++ b/man/dot-path_row_to_list.Rd @@ -34,7 +34,7 @@ generated file names.} \item{...}{Additional columns, ignored.} } \value{ -A \code{list} describing one operation. +(\code{list}) One operation description. } \description{ Convert one operation row to template data diff --git a/man/dot-paths_to_clean_df.Rd b/man/dot-paths_to_clean_df.Rd index b884725..f03df01 100644 --- a/man/dot-paths_to_clean_df.Rd +++ b/man/dot-paths_to_clean_df.Rd @@ -10,7 +10,8 @@ \item{paths}{(\code{rapid::class_paths}) API path definitions.} } \value{ -A \code{\link[tibble:tibble]{tibble::tibble()}} with one row per non-deprecated operation. +(\code{tibble}) A \code{\link[tibble:tibble]{tibble::tibble()}} with one row per non-deprecated +operation. } \description{ Convert API paths to an operations data frame diff --git a/man/dot-pkg_abort.Rd b/man/dot-pkg_abort.Rd index 47c00d4..4c9d03d 100644 --- a/man/dot-pkg_abort.Rd +++ b/man/dot-pkg_abort.Rd @@ -32,7 +32,7 @@ evaluate variables in error messages.} \code{\link[rlang:abort]{rlang::abort()}}.} } \value{ -Does not return. +(\code{NULL}) Does not return. } \description{ Signal a package-scoped error diff --git a/man/dot-pkg_inform.Rd b/man/dot-pkg_inform.Rd index 03836d8..ca339c9 100644 --- a/man/dot-pkg_inform.Rd +++ b/man/dot-pkg_inform.Rd @@ -32,7 +32,7 @@ evaluate variables in error messages.} \code{\link[rlang:abort]{rlang::inform()}}.} } \value{ -\code{NULL}, invisibly (called for message side effect). +(\code{NULL}, invisibly) Called for message side effect. } \description{ Signal a package-scoped message diff --git a/man/dot-pkg_warn.Rd b/man/dot-pkg_warn.Rd index 3e7a38d..6bc36ca 100644 --- a/man/dot-pkg_warn.Rd +++ b/man/dot-pkg_warn.Rd @@ -32,7 +32,7 @@ evaluate variables in error messages.} \code{\link[rlang:abort]{rlang::warn()}}.} } \value{ -\code{NULL}, invisibly (called for warning side effect). +(\code{NULL}, invisibly) Called for warning side effect. } \description{ Signal a package-scoped warning diff --git a/man/dot-prepare_params_df.Rd b/man/dot-prepare_params_df.Rd index 8362d54..2d6923b 100644 --- a/man/dot-prepare_params_df.Rd +++ b/man/dot-prepare_params_df.Rd @@ -10,7 +10,7 @@ \item{params_df}{(\code{data.frame}) Parameter metadata in tabular form.} } \value{ -A \code{data.frame} of prepared parameter metadata. +(\code{data.frame}) Prepared parameter metadata. } \description{ Prepare parameter metadata diff --git a/man/dot-remove_security_args.Rd b/man/dot-remove_security_args.Rd index 814b459..232147f 100644 --- a/man/dot-remove_security_args.Rd +++ b/man/dot-remove_security_args.Rd @@ -13,7 +13,7 @@ operation parameters (because they are defined once, separately).} } \value{ -A \code{list} of non-security parameters. +(\code{list}) Non-security parameters. } \description{ Remove security parameters diff --git a/man/dot-security_arg_description_clean.Rd b/man/dot-security_arg_description_clean.Rd index 89f35e1..4eb9200 100644 --- a/man/dot-security_arg_description_clean.Rd +++ b/man/dot-security_arg_description_clean.Rd @@ -12,7 +12,7 @@ \item{security_arg_name}{(\code{character(1)}) The argument name.} } \value{ -A named \code{list} with \code{name} and \code{description}. +(\code{list}) A named list with \code{name} and \code{description}. } \description{ Format one security argument help entry diff --git a/man/dot-security_args_compile.Rd b/man/dot-security_args_compile.Rd index 5a37921..db82de3 100644 --- a/man/dot-security_args_compile.Rd +++ b/man/dot-security_args_compile.Rd @@ -11,7 +11,7 @@ metadata.} } \value{ -A \code{list} of compiled security argument values. +(\code{list}) Compiled security argument values. } \description{ Compile security argument metadata diff --git a/man/dot-security_scheme_collection_finalize.Rd b/man/dot-security_scheme_collection_finalize.Rd index c2ae22e..11d3cad 100644 --- a/man/dot-security_scheme_collection_finalize.Rd +++ b/man/dot-security_scheme_collection_finalize.Rd @@ -11,7 +11,7 @@ metadata.} } \value{ -A \code{list} of finalized security metadata. +(\code{list}) Finalized security metadata. } \description{ Finalize collected security scheme data diff --git a/man/dot-security_scheme_rotate.Rd b/man/dot-security_scheme_rotate.Rd index b048fb4..5a825dc 100644 --- a/man/dot-security_scheme_rotate.Rd +++ b/man/dot-security_scheme_rotate.Rd @@ -20,7 +20,7 @@ security scheme details.} description from the API definition.} } \value{ -A \code{list} describing one security scheme. +(\code{list}) One security scheme description. } \description{ Convert one security scheme to a list diff --git a/man/dot-security_schemes_collect.Rd b/man/dot-security_schemes_collect.Rd index 095fef8..7118e38 100644 --- a/man/dot-security_schemes_collect.Rd +++ b/man/dot-security_schemes_collect.Rd @@ -11,7 +11,7 @@ from the API definition.} } \value{ -A \code{list} of security scheme metadata. +(\code{list}) Security scheme metadata. } \description{ Collect security scheme metadata diff --git a/man/dot-setup_r.Rd b/man/dot-setup_r.Rd index 7596659..2aba67e 100644 --- a/man/dot-setup_r.Rd +++ b/man/dot-setup_r.Rd @@ -13,7 +13,7 @@ files.} \item{include_stbl}{(\code{logical(1)}) Whether to add \code{stbl} to Imports.} } \value{ -\code{NULL} (invisibly). +(\code{NULL}, invisibly) Called for setup side effects. } \description{ Set up package directories and dependencies diff --git a/man/dot-stabilize_config.Rd b/man/dot-stabilize_config.Rd index 990d7cd..e8f812f 100644 --- a/man/dot-stabilize_config.Rd +++ b/man/dot-stabilize_config.Rd @@ -10,7 +10,7 @@ \item{config}{(\code{list}) Package-generation configuration data.} } \value{ -A stabilized \code{list}. +(\code{list}) A stabilized config list. } \description{ Stabilize beekeeper config values diff --git a/man/generate_pkg.Rd b/man/generate_pkg.Rd index 295bae5..6e5607c 100644 --- a/man/generate_pkg.Rd +++ b/man/generate_pkg.Rd @@ -29,8 +29,7 @@ config file.} files.} } \value{ -A character vector of paths to files that were added or updated, -invisibly. +(\code{character}, invisibly) Paths to files that were added or updated. } \description{ Creates or updates package files based on the information in a beekeeper diff --git a/man/op-lengthless-default.Rd b/man/op-lengthless-default.Rd index ccab4a5..7d386fc 100644 --- a/man/op-lengthless-default.Rd +++ b/man/op-lengthless-default.Rd @@ -13,7 +13,7 @@ x \%|0|\% y \item{y}{(\code{any}) The default value.} } \value{ -If \code{!length(x)}, will return \code{x}; otherwise returns \code{y}. +(\code{any}) If \code{!length(x)}, returns \code{x}; otherwise returns \code{y}. } \description{ Default value for length 0 diff --git a/man/op-na-coalesce.Rd b/man/op-na-coalesce.Rd index 84438e7..d37b2b3 100644 --- a/man/op-na-coalesce.Rd +++ b/man/op-na-coalesce.Rd @@ -14,8 +14,8 @@ x \%|\% y replace \code{NA} elements in \code{x}. Will be recycled to the same length as \code{x}.} } \value{ -A vector of the same length as \code{x}, where each \code{NA} element in \code{x} -is replaced by the corresponding element in \code{y}. +(\code{vector}) A vector of the same length as \code{x}, where each \code{NA} +element in \code{x} is replaced by the corresponding element in \code{y}. } \description{ Default value for NA elements in vectors diff --git a/man/op-no-char-default.Rd b/man/op-no-char-default.Rd index 2850b73..b0416ec 100644 --- a/man/op-no-char-default.Rd +++ b/man/op-no-char-default.Rd @@ -13,7 +13,7 @@ x \%|a|\% y \item{y}{(\code{character}) The default value.} } \value{ -If \code{!nzchar(x)}, will return \code{y}; otherwise returns \code{x}. +(\code{character}) If \code{!nzchar(x)}, returns \code{y}; otherwise returns \code{x}. } \description{ Default value for empty strings diff --git a/man/op-null-continuation.Rd b/man/op-null-continuation.Rd index c47e8a6..8dd6281 100644 --- a/man/op-null-continuation.Rd +++ b/man/op-null-continuation.Rd @@ -13,7 +13,7 @@ x \%&&\% y \item{y}{(\code{any}) The default value.} } \value{ -If \code{x} is \code{NULL}, will return \code{x}; otherwise returns \code{y}. +(\code{any}) If \code{x} is \code{NULL}, returns \code{x}; otherwise returns \code{y}. } \description{ Default value for non-\code{NULL} diff --git a/man/op-null-default.Rd b/man/op-null-default.Rd index 80a2af7..84b01c3 100644 --- a/man/op-null-default.Rd +++ b/man/op-null-default.Rd @@ -13,7 +13,7 @@ x \%||\% y \item{y}{(\code{any}) The default value.} } \value{ -If \code{x} is \code{NULL}, will return \code{y}; otherwise returns \code{x}. +(\code{any}) If \code{x} is \code{NULL}, returns \code{y}; otherwise returns \code{x}. } \description{ Default value for \code{NULL} diff --git a/man/read_api_definition.Rd b/man/read_api_definition.Rd index aa4ddf0..73bbe26 100644 --- a/man/read_api_definition.Rd +++ b/man/read_api_definition.Rd @@ -14,7 +14,7 @@ files.} definition (rapid) file.} } \value{ -A \code{\link[rapid:class_rapid]{rapid::class_rapid()}} with the definition of the API. +(\code{rapid::class_rapid}) The definition of the API. } \description{ Reads an RDS file (default name \verb{_beekeeper_rapid.rds}) with the API diff --git a/man/read_config.Rd b/man/read_config.Rd index 1360857..56ca530 100644 --- a/man/read_config.Rd +++ b/man/read_config.Rd @@ -14,7 +14,7 @@ files.} config file.} } \value{ -A \code{list} of configuration information, with elements \code{api_title}, +(\code{list}) Configuration information, with elements \code{api_title}, \code{api_abbr}, \code{api_version}, \code{rapid_file}, and \code{updated_on}. } \description{ diff --git a/man/use_beekeeper.Rd b/man/use_beekeeper.Rd index 57461e5..643f7af 100644 --- a/man/use_beekeeper.Rd +++ b/man/use_beekeeper.Rd @@ -30,9 +30,10 @@ config file.} definition (rapid) file.} } \value{ -The path to the configuration file, invisibly. The config file is -written as a side effect of this function. The rapid object is also -written, and the path to that file is saved in the config file. +(\code{character(1)}, invisibly) The path to the configuration file. +The config file is written as a side effect of this function. The rapid +object is also written, and the path to that file is saved in the config +file. } \description{ Create a configuration file for a package to use beekeeper. The configuration From dc3673388f7627de908633f235194f94a44b6727 Mon Sep 17 00:00:00 2001 From: Jon Harmon Date: Sun, 17 May 2026 07:16:51 -0500 Subject: [PATCH 11/13] Clean up and rearrange --- R/generate_pkg-setup.R | 67 --------------------- R/read_config.R | 66 ++++++++++++++++++++ R/use_beekeeper.R | 7 +-- man/dot-stabilize_config.Rd | 2 +- man/read_api_definition.Rd | 2 +- man/read_config.Rd | 2 +- man/use_beekeeper.Rd | 7 +-- tests/testthat/_snaps/generate_pkg-setup.md | 21 ------- tests/testthat/_snaps/read_config.md | 21 +++++++ tests/testthat/test-generate_pkg-setup.R | 15 ----- tests/testthat/test-read_config.R | 14 +++++ 11 files changed, 110 insertions(+), 114 deletions(-) create mode 100644 R/read_config.R create mode 100644 tests/testthat/_snaps/read_config.md create mode 100644 tests/testthat/test-read_config.R diff --git a/R/generate_pkg-setup.R b/R/generate_pkg-setup.R index 925ec0b..6804dfe 100644 --- a/R/generate_pkg-setup.R +++ b/R/generate_pkg-setup.R @@ -28,73 +28,6 @@ !is.null(root_file) } -#' Read a beekeeper config file -#' -#' Reads a YAML file (default name `_beekeeper.yml`) with configuration -#' information about the API and the package. This file is generated by -#' [use_beekeeper()], or can be created manually. -#' -#' The configuration information must contain these fields: -#' -#' - `api_title` (`character(1)`): The title of the API, used in documentation -#' and messages. -#' - `api_abbr` (`character(1)`): An abbreviation for the API, used in function -#' names and other identifiers. -#' - `api_version` (`character(1)`): The version of the API. -#' - `rapid_file` (`character(1)`): The name of the file (relative to the -#' package root) where the API definition is stored as an RDS file. By default, -#' this is `_beekeeper_rapid.rds`, and is generated by [use_beekeeper()] based -#' on an OpenAPI definition file. -#' - `updated_on` (`character(1)`): A timestamp of when the API definition was -#' last updated, in the format "YYYY-MM-DD HH:MM:SS" (UTC). -#' -#' @inheritParams .shared-params -#' @returns (`list`) Configuration information, with elements `api_title`, -#' `api_abbr`, `api_version`, `rapid_file`, and `updated_on`. -#' @export -read_config <- function(pkg_dir = ".", config_file = "_beekeeper.yml") { - config <- yaml::read_yaml(fs::path(pkg_dir, config_file)) - return(.stabilize_config(config)) -} - -#' Stabilize beekeeper config values -#' -#' @inheritParams .shared-params -#' @returns (`list`) A stabilized config list. -#' @keywords internal -.stabilize_config <- function(config) { - config$api_title <- stbl::stabilize_character_scalar(config$api_title) - config$api_abbr <- stbl::stabilize_character_scalar(config$api_abbr) - config$api_version <- stbl::stabilize_character_scalar( - config$api_version, - allow_null = TRUE - ) - config$rapid_file <- stbl::stabilize_character_scalar(config$rapid_file) - config$updated_on <- config$updated_on %&&% - strptime( - config$updated_on, - format = "%Y-%m-%d %H:%M:%S", - tz = "UTC" - ) - return(config) -} - -#' Read an API definition file -#' -#' Reads an RDS file (default name `_beekeeper_rapid.rds`) with the API -#' definition stored as a [rapid::class_rapid()] object. This file is generated -#' by [use_beekeeper()] based on an OpenAPI definition file. -#' -#' @inheritParams .shared-params -#' @returns (`rapid::class_rapid`) The definition of the API. -#' @export -read_api_definition <- function( - pkg_dir = ".", - rapid_file = "_beekeeper_rapid.rds" -) { - readRDS(fs::path(pkg_dir, rapid_file)) -} - #' Set up package directories and dependencies #' #' @inheritParams .shared-params diff --git a/R/read_config.R b/R/read_config.R new file mode 100644 index 0000000..cd1874f --- /dev/null +++ b/R/read_config.R @@ -0,0 +1,66 @@ +#' Read a beekeeper config file +#' +#' Reads a YAML file (default name `_beekeeper.yml`) with configuration +#' information about the API and the package. This file is generated by +#' [use_beekeeper()], or can be created manually. +#' +#' The configuration information must contain these fields: +#' +#' - `api_title` (`character(1)`): The title of the API, used in documentation +#' and messages. +#' - `api_abbr` (`character(1)`): An abbreviation for the API, used in function +#' names and other identifiers. +#' - `api_version` (`character(1)`): The version of the API. +#' - `rapid_file` (`character(1)`): The name of the file (relative to the +#' package root) where the API definition is stored as an RDS file. By default, +#' this is `_beekeeper_rapid.rds`, and is generated by [use_beekeeper()] based +#' on an OpenAPI definition file. +#' - `updated_on` (`character(1)`): A timestamp of when the API definition was +#' last updated, in the format "YYYY-MM-DD HH:MM:SS" (UTC). +#' +#' @inheritParams .shared-params +#' @returns (`list`) Configuration information, with elements `api_title`, +#' `api_abbr`, `api_version`, `rapid_file`, and `updated_on`. +#' @export +read_config <- function(pkg_dir = ".", config_file = "_beekeeper.yml") { + config <- yaml::read_yaml(fs::path(pkg_dir, config_file)) + return(.stabilize_config(config)) +} + +#' Stabilize beekeeper config values +#' +#' @inheritParams .shared-params +#' @returns (`list`) A stabilized config list. +#' @keywords internal +.stabilize_config <- function(config) { + config$api_title <- stbl::stabilize_character_scalar(config$api_title) + config$api_abbr <- stbl::stabilize_character_scalar(config$api_abbr) + config$api_version <- stbl::stabilize_character_scalar( + config$api_version, + allow_null = TRUE + ) + config$rapid_file <- stbl::stabilize_character_scalar(config$rapid_file) + config$updated_on <- config$updated_on %&&% + strptime( + config$updated_on, + format = "%Y-%m-%d %H:%M:%S", + tz = "UTC" + ) + return(config) +} + +#' Read an API definition file +#' +#' Reads an RDS file (default name `_beekeeper_rapid.rds`) with the API +#' definition stored as a [rapid::class_rapid()] object. This file is generated +#' by [use_beekeeper()] based on an OpenAPI definition file. +#' +#' @inheritParams .shared-params +#' @returns (`rapid::class_rapid`) The definition of the API. +#' @export +read_api_definition <- function( + pkg_dir = ".", + rapid_file = "_beekeeper_rapid.rds" +) { + readRDS(fs::path(pkg_dir, rapid_file)) +} diff --git a/R/use_beekeeper.R b/R/use_beekeeper.R index 1fd04c7..efecfe9 100644 --- a/R/use_beekeeper.R +++ b/R/use_beekeeper.R @@ -11,10 +11,9 @@ #' generated by reading such a document. #' @inheritParams .shared-params #' -#' @returns (`character(1)`, invisibly) The path to the configuration file. -#' The config file is written as a side effect of this function. The rapid -#' object is also written, and the path to that file is saved in the config -#' file. +#' @returns (`character(1)`, invisibly) The path to the configuration file. The +#' config file is written as a side effect of this function. The rapid object +#' is also written, and the path to that file is saved in the config file. #' @export use_beekeeper <- function( x, diff --git a/man/dot-stabilize_config.Rd b/man/dot-stabilize_config.Rd index e8f812f..80b0b48 100644 --- a/man/dot-stabilize_config.Rd +++ b/man/dot-stabilize_config.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/generate_pkg-setup.R +% Please edit documentation in R/read_config.R \name{.stabilize_config} \alias{.stabilize_config} \title{Stabilize beekeeper config values} diff --git a/man/read_api_definition.Rd b/man/read_api_definition.Rd index 73bbe26..a043f2c 100644 --- a/man/read_api_definition.Rd +++ b/man/read_api_definition.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/generate_pkg-setup.R +% Please edit documentation in R/read_config.R \name{read_api_definition} \alias{read_api_definition} \title{Read an API definition file} diff --git a/man/read_config.Rd b/man/read_config.Rd index 56ca530..9dadade 100644 --- a/man/read_config.Rd +++ b/man/read_config.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/generate_pkg-setup.R +% Please edit documentation in R/read_config.R \name{read_config} \alias{read_config} \title{Read a beekeeper config file} diff --git a/man/use_beekeeper.Rd b/man/use_beekeeper.Rd index 643f7af..2a6b33c 100644 --- a/man/use_beekeeper.Rd +++ b/man/use_beekeeper.Rd @@ -30,10 +30,9 @@ config file.} definition (rapid) file.} } \value{ -(\code{character(1)}, invisibly) The path to the configuration file. -The config file is written as a side effect of this function. The rapid -object is also written, and the path to that file is saved in the config -file. +(\code{character(1)}, invisibly) The path to the configuration file. The +config file is written as a side effect of this function. The rapid object +is also written, and the path to that file is saved in the config file. } \description{ Create a configuration file for a package to use beekeeper. The configuration diff --git a/tests/testthat/_snaps/generate_pkg-setup.md b/tests/testthat/_snaps/generate_pkg-setup.md index d0318ea..dd14438 100644 --- a/tests/testthat/_snaps/generate_pkg-setup.md +++ b/tests/testthat/_snaps/generate_pkg-setup.md @@ -7,24 +7,3 @@ ! Can't generate package files outside of a package. TMPDIR is not inside a package. -# read_config() reads configs - - Code - config - Output - $api_title - [1] "APIs.guru" - - $api_abbr - [1] "guru" - - $api_version - [1] "2.2.0" - - $rapid_file - [1] "_beekeeper_rapid.rds" - - $updated_on - [1] "2026-05-12 07:57:02 UTC" - - diff --git a/tests/testthat/_snaps/read_config.md b/tests/testthat/_snaps/read_config.md new file mode 100644 index 0000000..0a9e06d --- /dev/null +++ b/tests/testthat/_snaps/read_config.md @@ -0,0 +1,21 @@ +# read_config() reads configs + + Code + config + Output + $api_title + [1] "APIs.guru" + + $api_abbr + [1] "guru" + + $api_version + [1] "2.2.0" + + $rapid_file + [1] "_beekeeper_rapid.rds" + + $updated_on + [1] "2026-05-12 07:57:02 UTC" + + diff --git a/tests/testthat/test-generate_pkg-setup.R b/tests/testthat/test-generate_pkg-setup.R index 07c570a..cdd213a 100644 --- a/tests/testthat/test-generate_pkg-setup.R +++ b/tests/testthat/test-generate_pkg-setup.R @@ -13,21 +13,6 @@ test_that(".assert_is_pkg() isn't obtrusive for packages", { }) }) -test_that("read_config() reads configs", { - config <- read_config(pkg_dir = test_path("_fixtures", "guru")) - expect_s3_class(config$updated_on, c("POSIXlt", "POSIXt")) - expect_snapshot({ - config - }) -}) - -test_that("read_api_definition() reads api_definitions", { - api_definition <- read_api_definition( - pkg_dir = test_path("_fixtures", "guru") - ) - expect_s7_class(api_definition, rapid::class_rapid) -}) - test_that(".setup_r() sets up dependencies (#16)", { skip_on_cran() diff --git a/tests/testthat/test-read_config.R b/tests/testthat/test-read_config.R new file mode 100644 index 0000000..7a5a738 --- /dev/null +++ b/tests/testthat/test-read_config.R @@ -0,0 +1,14 @@ +test_that("read_config() reads configs", { + config <- read_config(pkg_dir = test_path("_fixtures", "guru")) + expect_s3_class(config$updated_on, c("POSIXlt", "POSIXt")) + expect_snapshot({ + config + }) +}) + +test_that("read_api_definition() reads api_definitions", { + api_definition <- read_api_definition( + pkg_dir = test_path("_fixtures", "guru") + ) + expect_s7_class(api_definition, rapid::class_rapid) +}) From 97bc1e1d8f49fba994568f850603e4e4a455704d Mon Sep 17 00:00:00 2001 From: Jon Harmon Date: Sun, 17 May 2026 07:30:11 -0500 Subject: [PATCH 12/13] Document `.is_pkg()` param --- R/generate_pkg-setup.R | 4 ++-- man/dot-assert_is_pkg.Rd | 4 ++++ man/dot-is_pkg.Rd | 4 ++++ 3 files changed, 10 insertions(+), 2 deletions(-) diff --git a/R/generate_pkg-setup.R b/R/generate_pkg-setup.R index 6804dfe..f52873f 100644 --- a/R/generate_pkg-setup.R +++ b/R/generate_pkg-setup.R @@ -1,7 +1,6 @@ #' Error if not in package #' -#' @inheritParams .is_pkg -#' +#' @inheritParams .shared-params #' @returns (`NULL`, invisibly) Called for error side effect. #' @keywords internal .assert_is_pkg <- function(pkg_dir = usethis::proj_get()) { @@ -18,6 +17,7 @@ #' #' Inspired by usethis:::is_package. #' +#' @inheritParams .shared-params #' @returns (`logical(1)`) `TRUE` if the project is a package, `FALSE` if not. #' @keywords internal .is_pkg <- function(pkg_dir = usethis::proj_get()) { diff --git a/man/dot-assert_is_pkg.Rd b/man/dot-assert_is_pkg.Rd index 2bf5911..e3c85ea 100644 --- a/man/dot-assert_is_pkg.Rd +++ b/man/dot-assert_is_pkg.Rd @@ -6,6 +6,10 @@ \usage{ .assert_is_pkg(pkg_dir = usethis::proj_get()) } +\arguments{ +\item{pkg_dir}{(\code{character(1)} or \code{fs_path}) The directory containing package +files.} +} \value{ (\code{NULL}, invisibly) Called for error side effect. } diff --git a/man/dot-is_pkg.Rd b/man/dot-is_pkg.Rd index df3b40d..ccd6dce 100644 --- a/man/dot-is_pkg.Rd +++ b/man/dot-is_pkg.Rd @@ -6,6 +6,10 @@ \usage{ .is_pkg(pkg_dir = usethis::proj_get()) } +\arguments{ +\item{pkg_dir}{(\code{character(1)} or \code{fs_path}) The directory containing package +files.} +} \value{ (\code{logical(1)}) \code{TRUE} if the project is a package, \code{FALSE} if not. } From 08a63bf6bb7d30536a6a7828ce347f519818b8e8 Mon Sep 17 00:00:00 2001 From: Jon Harmon Date: Sun, 17 May 2026 07:38:40 -0500 Subject: [PATCH 13/13] Update templates (and corresponding fixtures) to better match `@returns` style. --- inst/templates/paths.R | 2 +- tests/testthat/_fixtures/fec/paths-audit-get_audit_case.R | 2 +- tests/testthat/_fixtures/fec/paths-audit-get_audit_category.R | 2 +- .../_fixtures/fec/paths-audit-get_audit_primary_category.R | 2 +- .../_fixtures/fec/paths-audit-get_names_audit_candidates.R | 2 +- .../_fixtures/fec/paths-audit-get_names_audit_committees.R | 2 +- .../_fixtures/fec/paths-debts-get_schedules_schedule_d.R | 2 +- .../_fixtures/fec/paths-debts-get_schedules_schedule_d_sub_id.R | 2 +- tests/testthat/_fixtures/fec/paths-legal-get_legal_search.R | 2 +- tests/testthat/_fixtures/guru/paths-apis-get_api.R | 2 +- tests/testthat/_fixtures/guru/paths-apis-get_metrics.R | 2 +- tests/testthat/_fixtures/guru/paths-apis-get_provider.R | 2 +- tests/testthat/_fixtures/guru/paths-apis-get_providers.R | 2 +- tests/testthat/_fixtures/guru/paths-apis-get_service_api.R | 2 +- tests/testthat/_fixtures/guru/paths-apis-get_services.R | 2 +- tests/testthat/_fixtures/guru/paths-apis-list_apis.R | 2 +- .../_fixtures/header_cookie/paths-things-search_things.R | 2 +- tests/testthat/_fixtures/trello/paths-board-add_boards.R | 2 +- 18 files changed, 18 insertions(+), 18 deletions(-) diff --git a/inst/templates/paths.R b/inst/templates/paths.R index 5073515..ac06e06 100644 --- a/inst/templates/paths.R +++ b/inst/templates/paths.R @@ -22,7 +22,7 @@ } #' @rdname {{api_abbr}}_{{operation_id}} -#' @returns `req_{{api_abbr}}_{{operation_id}}()`: A `httr2_request` request object. +#' @returns `req_{{api_abbr}}_{{operation_id}}()`: (`httr2_request`) A [httr2::request()] object. req_{{api_abbr}}_{{operation_id}} <- function({{#args}}{{{args}}}{{/args}}{{#has_security}}{{#args}}, {{/args}}{{{security_signature}}}{{/has_security}}) { {{#validations}} {{name}} <- stbl::{{to_r}}({{name}}) diff --git a/tests/testthat/_fixtures/fec/paths-audit-get_audit_case.R b/tests/testthat/_fixtures/fec/paths-audit-get_audit_case.R index df57209..e53dea6 100644 --- a/tests/testthat/_fixtures/fec/paths-audit-get_audit_case.R +++ b/tests/testthat/_fixtures/fec/paths-audit-get_audit_case.R @@ -85,7 +85,7 @@ fec_get_audit_case <- function( } #' @rdname fec_get_audit_case -#' @returns `req_fec_get_audit_case()`: A `httr2_request` request object. +#' @returns `req_fec_get_audit_case()`: (`httr2_request`) A [httr2::request()] object. req_fec_get_audit_case <- function( audit_case_id, cycle, diff --git a/tests/testthat/_fixtures/fec/paths-audit-get_audit_category.R b/tests/testthat/_fixtures/fec/paths-audit-get_audit_category.R index f2c048d..a13b46e 100644 --- a/tests/testthat/_fixtures/fec/paths-audit-get_audit_category.R +++ b/tests/testthat/_fixtures/fec/paths-audit-get_audit_category.R @@ -52,7 +52,7 @@ fec_get_audit_category <- function( } #' @rdname fec_get_audit_category -#' @returns `req_fec_get_audit_category()`: A `httr2_request` request object. +#' @returns `req_fec_get_audit_category()`: (`httr2_request`) A [httr2::request()] object. req_fec_get_audit_category <- function( sort_nulls_last, page, diff --git a/tests/testthat/_fixtures/fec/paths-audit-get_audit_primary_category.R b/tests/testthat/_fixtures/fec/paths-audit-get_audit_primary_category.R index 4641347..beba2e2 100644 --- a/tests/testthat/_fixtures/fec/paths-audit-get_audit_primary_category.R +++ b/tests/testthat/_fixtures/fec/paths-audit-get_audit_primary_category.R @@ -52,7 +52,7 @@ fec_get_audit_primary_category <- function( } #' @rdname fec_get_audit_primary_category -#' @returns `req_fec_get_audit_primary_category()`: A `httr2_request` request object. +#' @returns `req_fec_get_audit_primary_category()`: (`httr2_request`) A [httr2::request()] object. req_fec_get_audit_primary_category <- function( sort_nulls_last, page, diff --git a/tests/testthat/_fixtures/fec/paths-audit-get_names_audit_candidates.R b/tests/testthat/_fixtures/fec/paths-audit-get_names_audit_candidates.R index 76727c7..402df75 100644 --- a/tests/testthat/_fixtures/fec/paths-audit-get_names_audit_candidates.R +++ b/tests/testthat/_fixtures/fec/paths-audit-get_names_audit_candidates.R @@ -23,7 +23,7 @@ fec_get_names_audit_candidates <- function(q, api_key = Sys.getenv("FEC_API_KEY" } #' @rdname fec_get_names_audit_candidates -#' @returns `req_fec_get_names_audit_candidates()`: A `httr2_request` request object. +#' @returns `req_fec_get_names_audit_candidates()`: (`httr2_request`) A [httr2::request()] object. req_fec_get_names_audit_candidates <- function(q, api_key = Sys.getenv("FEC_API_KEY")) { fec_req_prepare( path = "/names/audit_candidates/", diff --git a/tests/testthat/_fixtures/fec/paths-audit-get_names_audit_committees.R b/tests/testthat/_fixtures/fec/paths-audit-get_names_audit_committees.R index 9e6d5a5..43ee3cd 100644 --- a/tests/testthat/_fixtures/fec/paths-audit-get_names_audit_committees.R +++ b/tests/testthat/_fixtures/fec/paths-audit-get_names_audit_committees.R @@ -29,7 +29,7 @@ fec_get_names_audit_committees <- function( } #' @rdname fec_get_names_audit_committees -#' @returns `req_fec_get_names_audit_committees()`: A `httr2_request` request object. +#' @returns `req_fec_get_names_audit_committees()`: (`httr2_request`) A [httr2::request()] object. req_fec_get_names_audit_committees <- function( q, api_key = Sys.getenv("FEC_API_KEY") diff --git a/tests/testthat/_fixtures/fec/paths-debts-get_schedules_schedule_d.R b/tests/testthat/_fixtures/fec/paths-debts-get_schedules_schedule_d.R index 9e61f1b..80850c7 100644 --- a/tests/testthat/_fixtures/fec/paths-debts-get_schedules_schedule_d.R +++ b/tests/testthat/_fixtures/fec/paths-debts-get_schedules_schedule_d.R @@ -97,7 +97,7 @@ fec_get_schedules_schedule_d <- function( } #' @rdname fec_get_schedules_schedule_d -#' @returns `req_fec_get_schedules_schedule_d()`: A `httr2_request` request object. +#' @returns `req_fec_get_schedules_schedule_d()`: (`httr2_request`) A [httr2::request()] object. req_fec_get_schedules_schedule_d <- function( creditor_debtor_name, max_image_number, diff --git a/tests/testthat/_fixtures/fec/paths-debts-get_schedules_schedule_d_sub_id.R b/tests/testthat/_fixtures/fec/paths-debts-get_schedules_schedule_d_sub_id.R index 0a2a9bf..6b78bef 100644 --- a/tests/testthat/_fixtures/fec/paths-debts-get_schedules_schedule_d_sub_id.R +++ b/tests/testthat/_fixtures/fec/paths-debts-get_schedules_schedule_d_sub_id.R @@ -49,7 +49,7 @@ fec_get_schedules_schedule_d_sub_id <- function( } #' @rdname fec_get_schedules_schedule_d_sub_id -#' @returns `req_fec_get_schedules_schedule_d_sub_id()`: A `httr2_request` request object. +#' @returns `req_fec_get_schedules_schedule_d_sub_id()`: (`httr2_request`) A [httr2::request()] object. req_fec_get_schedules_schedule_d_sub_id <- function( sort_nulls_last, per_page, diff --git a/tests/testthat/_fixtures/fec/paths-legal-get_legal_search.R b/tests/testthat/_fixtures/fec/paths-legal-get_legal_search.R index e622c7f..1ebc4ac 100644 --- a/tests/testthat/_fixtures/fec/paths-legal-get_legal_search.R +++ b/tests/testthat/_fixtures/fec/paths-legal-get_legal_search.R @@ -154,7 +154,7 @@ fec_get_legal_search <- function( } #' @rdname fec_get_legal_search -#' @returns `req_fec_get_legal_search()`: A `httr2_request` request object. +#' @returns `req_fec_get_legal_search()`: (`httr2_request`) A [httr2::request()] object. req_fec_get_legal_search <- function( hits_returned, af_report_year, diff --git a/tests/testthat/_fixtures/guru/paths-apis-get_api.R b/tests/testthat/_fixtures/guru/paths-apis-get_api.R index 9139aaa..940925a 100644 --- a/tests/testthat/_fixtures/guru/paths-apis-get_api.R +++ b/tests/testthat/_fixtures/guru/paths-apis-get_api.R @@ -23,7 +23,7 @@ guru_get_api <- function(provider, api, max_reqs = Inf, max_tries_per_req = 3) { } #' @rdname guru_get_api -#' @returns `req_guru_get_api()`: A `httr2_request` request object. +#' @returns `req_guru_get_api()`: (`httr2_request`) A [httr2::request()] object. req_guru_get_api <- function(provider, api) { provider <- stbl::to_chr_scalar(provider) api <- stbl::to_chr_scalar(api) diff --git a/tests/testthat/_fixtures/guru/paths-apis-get_metrics.R b/tests/testthat/_fixtures/guru/paths-apis-get_metrics.R index 04d2e6b..b4868f1 100644 --- a/tests/testthat/_fixtures/guru/paths-apis-get_metrics.R +++ b/tests/testthat/_fixtures/guru/paths-apis-get_metrics.R @@ -21,7 +21,7 @@ guru_get_metrics <- function(max_reqs = Inf, max_tries_per_req = 3) { } #' @rdname guru_get_metrics -#' @returns `req_guru_get_metrics()`: A `httr2_request` request object. +#' @returns `req_guru_get_metrics()`: (`httr2_request`) A [httr2::request()] object. req_guru_get_metrics <- function() { guru_req_prepare( path = "/metrics.json", diff --git a/tests/testthat/_fixtures/guru/paths-apis-get_provider.R b/tests/testthat/_fixtures/guru/paths-apis-get_provider.R index 8efb4d5..078304a 100644 --- a/tests/testthat/_fixtures/guru/paths-apis-get_provider.R +++ b/tests/testthat/_fixtures/guru/paths-apis-get_provider.R @@ -22,7 +22,7 @@ guru_get_provider <- function(provider, max_reqs = Inf, max_tries_per_req = 3) { } #' @rdname guru_get_provider -#' @returns `req_guru_get_provider()`: A `httr2_request` request object. +#' @returns `req_guru_get_provider()`: (`httr2_request`) A [httr2::request()] object. req_guru_get_provider <- function(provider) { provider <- stbl::to_chr_scalar(provider) guru_req_prepare( diff --git a/tests/testthat/_fixtures/guru/paths-apis-get_providers.R b/tests/testthat/_fixtures/guru/paths-apis-get_providers.R index ca20227..823d972 100644 --- a/tests/testthat/_fixtures/guru/paths-apis-get_providers.R +++ b/tests/testthat/_fixtures/guru/paths-apis-get_providers.R @@ -21,7 +21,7 @@ guru_get_providers <- function(max_reqs = Inf, max_tries_per_req = 3) { } #' @rdname guru_get_providers -#' @returns `req_guru_get_providers()`: A `httr2_request` request object. +#' @returns `req_guru_get_providers()`: (`httr2_request`) A [httr2::request()] object. req_guru_get_providers <- function() { guru_req_prepare( path = "/providers.json", diff --git a/tests/testthat/_fixtures/guru/paths-apis-get_service_api.R b/tests/testthat/_fixtures/guru/paths-apis-get_service_api.R index 99a0df0..1343762 100644 --- a/tests/testthat/_fixtures/guru/paths-apis-get_service_api.R +++ b/tests/testthat/_fixtures/guru/paths-apis-get_service_api.R @@ -24,7 +24,7 @@ guru_get_service_api <- function(provider, service, api, max_reqs = Inf, max_tri } #' @rdname guru_get_service_api -#' @returns `req_guru_get_service_api()`: A `httr2_request` request object. +#' @returns `req_guru_get_service_api()`: (`httr2_request`) A [httr2::request()] object. req_guru_get_service_api <- function(provider, service, api) { provider <- stbl::to_chr_scalar(provider) service <- stbl::to_chr_scalar(service) diff --git a/tests/testthat/_fixtures/guru/paths-apis-get_services.R b/tests/testthat/_fixtures/guru/paths-apis-get_services.R index 92f3245..45e8f43 100644 --- a/tests/testthat/_fixtures/guru/paths-apis-get_services.R +++ b/tests/testthat/_fixtures/guru/paths-apis-get_services.R @@ -22,7 +22,7 @@ guru_get_services <- function(provider, max_reqs = Inf, max_tries_per_req = 3) { } #' @rdname guru_get_services -#' @returns `req_guru_get_services()`: A `httr2_request` request object. +#' @returns `req_guru_get_services()`: (`httr2_request`) A [httr2::request()] object. req_guru_get_services <- function(provider) { provider <- stbl::to_chr_scalar(provider) guru_req_prepare( diff --git a/tests/testthat/_fixtures/guru/paths-apis-list_apis.R b/tests/testthat/_fixtures/guru/paths-apis-list_apis.R index d8a7e16..df70e2c 100644 --- a/tests/testthat/_fixtures/guru/paths-apis-list_apis.R +++ b/tests/testthat/_fixtures/guru/paths-apis-list_apis.R @@ -21,7 +21,7 @@ guru_list_apis <- function(max_reqs = Inf, max_tries_per_req = 3) { } #' @rdname guru_list_apis -#' @returns `req_guru_list_apis()`: A `httr2_request` request object. +#' @returns `req_guru_list_apis()`: (`httr2_request`) A [httr2::request()] object. req_guru_list_apis <- function() { guru_req_prepare( path = "/list.json", diff --git a/tests/testthat/_fixtures/header_cookie/paths-things-search_things.R b/tests/testthat/_fixtures/header_cookie/paths-things-search_things.R index b8c3980..2140308 100644 --- a/tests/testthat/_fixtures/header_cookie/paths-things-search_things.R +++ b/tests/testthat/_fixtures/header_cookie/paths-things-search_things.R @@ -24,7 +24,7 @@ test_search_things <- function(x_auth_token, session_id, q, max_reqs = Inf, max_ } #' @rdname test_search_things -#' @returns `req_test_search_things()`: A `httr2_request` request object. +#' @returns `req_test_search_things()`: (`httr2_request`) A [httr2::request()] object. req_test_search_things <- function(x_auth_token, session_id, q) { x_auth_token <- stbl::to_chr_scalar(x_auth_token) session_id <- stbl::to_chr_scalar(session_id) diff --git a/tests/testthat/_fixtures/trello/paths-board-add_boards.R b/tests/testthat/_fixtures/trello/paths-board-add_boards.R index 26663e9..97e0c70 100644 --- a/tests/testthat/_fixtures/trello/paths-board-add_boards.R +++ b/tests/testthat/_fixtures/trello/paths-board-add_boards.R @@ -24,7 +24,7 @@ token = Sys.getenv("TRELLO_TOKEN"), max_reqs = Inf, max_tries_per_req = 3) { } #' @rdname trello_add_boards -#' @returns `req_trello_add_boards()`: A `httr2_request` request object. +#' @returns `req_trello_add_boards()`: (`httr2_request`) A [httr2::request()] object. req_trello_add_boards <- function(key = Sys.getenv("TRELLO_KEY"), token = Sys.getenv("TRELLO_TOKEN")) { trello_req_prepare(