documented internal functions a bit more clearly, notably adding whic…

…h functions call them

R/ct_build_request.R

@@ -1,12 +1,10 @@
 #' Build a valid request object from the checked parameters
 #'
-#' This function takes the necessary parameters and creates a httr2 request to be performed this request can then be used in a second function, to actually return the data
+#' This is an internal function takes the necessary parameters from `ct_check_params()`
+#' and creates a httr2 request to be performed. This request can then be used in a second function, `ct_perform_request()` to actually return the data.
+#' It is called internally ct `ct_get_data()`
 #'
-#' @param params a named vector of parameters for the comtrade request
-#'
-#' @param primary_token Your primary token. Default is to check in environment for stored token, if not passed through the `set_primary_comtrade_key` function
-#'
-#' @param verbose whether the function sends status updates to the console
+#' @param params a named vector of parameters for the comtrade request, result from `ct_check_params()`.
 #'
 #' @examplesIf interactive()
 #' # Build request from checked parameters
@@ -29,6 +27,7 @@
 #'                                             update = FALSE ))
 #'
 #' @returns a httr2 request object
+#' @inheritParams ct_get_data
 ct_build_request <- function(params,
                                    primary_token = NULL,
                                    verbose = FALSE) {

R/ct_check_params.R

@@ -1,10 +1,12 @@
 #' Check that input parameters are valid and in compliance with UN Comtrade APIs.
 #'
-#' @inheritParams ct_get_data
+#' This is an internal function that is called by `ct_get_data()` and processes
+#' most arguments that are passed to it according to the relevant limitations of the
+#' official Comtrade API.
 #'
 #' @returns Returns a list of named parameters for building a request.
 #'
-#' @noRd
+#' @inheritParams ct_get_data
 ct_check_params <- function(type,
                             frequency,
                             commodity_classification,

R/ct_perform_request.R

@@ -1,13 +1,12 @@
 #' Performs the request to the Comtrade API
 #'
-#' Performs the request and returns an error body with the respective error returned by the Comtrade API. Also throttles all requests to 1 request per 6 seconds, or 10 requests per minute.
+#' This function is internally called by `ct_get_data()` and performs the request constructed by `ct_build_request()` and returns an error body with the respective error returned by the Comtrade API.
+#' By default throttles all requests to 1 request per 6 seconds, or 10 requests per minute, but it adjusts automatically if the
+#' API asks for longer waiting times.
 #'
 #' @param req a valid comtrade request built by the `ct_build_request()` function
-#' @param requests_per_second rate of requests per second executed, usually specified as a fraction, e.g. 10/60 for 10 requests per minute, see \link[httr2]{req_throttle()} for details.
 #'
-#' @param verbose whether the function sends status updates to the console
-#'
-#' @returns json data from comtrade and possible error codes
+#' @returns JSON data from comtrade, data.frame with results or error codes.
 #' @examplesIf interactive()
 #' ct_get_data(commodity_code = NULL,
 #'             reporter = 'CHN',
@@ -17,6 +16,7 @@
 #'             flow_direction = 'import')
 #' req <- httr2::last_request()
 #' resp <- ct_perform_request(req, requests_per_second = 10/60, verbose = FALSE)
+#' @inheritParams ct_get_data
 ct_perform_request <- function(req, requests_per_second, verbose = FALSE) {
 
     if (verbose) {

R/ct_process_response.R

@@ -1,11 +1,9 @@
 #' Processes the response object
 #'
-#' The function processes the httr2response object, parses the json and adds the respective iso codes for the reporter and partner countries, as well as the commodity code description.
+#' The function is internally called by `ct_get_data()` and processes the httr2response object returned by `ct_perform_request()`, it parses the JSON and adds the respective ISO codes for the reporter and partner countries, as well as the commodity code description.
 #'
 #' @param resp a valid httr2 response object created from the function `ct_perform_request()`
-#' @param verbose whether the function sends status updates to the console
 #'
-#' @inheritParams ct_get_data
 #' @returns a data.frame object with the results
 #'
 #' @examplesIf interactive()
@@ -18,6 +16,7 @@
 #' req <- httr2::last_request()
 #' resp <- ct_perform_request(req, requests_per_second = 10/60, verbose = FALSE)
 #' data <- ct_process_response(resp)
+#' @inheritParams ct_get_data
 ct_process_response <- function(resp, verbose = FALSE, tidy_cols) {
   result <- resp |>
     httr2::resp_body_json(simplifyVector = TRUE)