docs: fetch_args_list its own page, various minor

Author: dsweber2

R/epidatacall.R

@@ -3,29 +3,33 @@
 #' @aliases epidata_call
 #'
 #' @description
-#' `epidata_call` objects are generated by endpoint functions like
-#' [`covidcast`]; should be piped into the `fetch` function to fetch and format
-#' the data. For most endpoints this will return a tibble, but a few
-#' non-COVIDCAST endpoints only support will return a JSON-like list instead.
+#' `epidata_call` objects are generated internally by endpoint functions like
+#'   [`covidcast`]; by default, they are piped directly into the `fetch`
+#'   function to fetch and format the data. For most endpoints this will return
+#'   a tibble, but a few non-COVIDCAST endpoints only support will return a
+#'   JSON-like list instead.
 #'
 #' `create_epidata_call` is the constructor for `epidata_call` objects, but you
-#' should not need to use it directly; instead, use an endpoint function, e.g.,
-#' [`covidcast`], to generate an `epidata_call` for the data of interest.
+#'   should not need to use it directly; instead, use an endpoint function,
+#'   e.g., [`covidcast`], to generate an `epidata_call` for the data of
+#'   interest.
 #'
-#' There are some other functions available for debugging and advanced usage:
-#' - `request_url` (for debugging):  outputs the request URL from which data
-#'    would be fetched (note additional parameters below)
+#' There are some other functions available for debugging and advanced usage: -
+#'   `request_url` (for debugging):  outputs the request URL from which data
+#'   would be fetched (note additional parameters below)
 #'
 #' @examples
 #' \dontrun{
-#' covidcast(
+#' call <- covidcast(
 #'   source = "jhu-csse",
 #'   signals = "confirmed_7dav_incidence_prop",
 #'   time_type = "day",
 #'   geo_type = "state",
 #'   time_values = epirange(20200601, 20200801),
-#'   geo_values = c("ca", "fl")
+#'   geo_values = c("ca", "fl"),
+#'   fetch_args = fetch_args_list(make_call = FALSE)
 #' )
+#' call %>% fetch()
 #' }
 #'
 #' @param endpoint the epidata endpoint to call
@@ -98,28 +102,33 @@ print.epidata_call <- function(x, ...) {
   ))
 }
 
-#' Fetch args
-#' @rdname epidata_call
+#' Customize fetch settings
+#' @rdname fetch_args_list
 #' @aliases fetch_args
 #'
 #' A constructor for `fetch_args` objects, which are used to pass arguments to
 #' the `fetch` function.
 #'
 #' @param fields a list of epidata fields to return, or NULL to return all
 #'  fields (default) e.g. c("time_value", "value") to return only the
-#' time_value and value fields or c("-direction") to return everything except
-#' the direction field
-#' @param disable_date_parsing disable automatic date parsing
+#'  time_value and value fields or c("-direction") to return everything except
+#'  the direction field
+#' @param disable_date_parsing disable automatic date parsing; by default `FALSE`
 #' @param disable_data_frame_parsing disable automatic conversion to data frame; this
-#'   is only supported by endpoints that only support the 'classic' format (non-tabular)
-#' @param return_empty boolean that allows returning an empty tibble if there is no data
-#' @param timeout_seconds the maximum amount of time to wait for a response
-#' @param base_url base URL to use
+#'  is only supported by endpoints that only support the 'classic' format (non-tabular).
+#'  by default `FALSE`
+#' @param return_empty boolean that allows returning an empty tibble if there is no data;
+#'  by default `FALSE`
+#' @param timeout_seconds the maximum amount of time to wait for a response; by default
+#'  `FALSE`
+#' @param base_url base URL to use; by default `NULL`, which means the global base url
+#'  `"https://api.delphi.cmu.edu/epidata/"`
 #' @param make_call boolean that allows skipping the call to the API and instead
-#'  returns the `epidata_call` object (useful for debugging)
-#' @param debug boolean that allows returning the raw response from the API
+#'  returns the `epidata_call` object (useful for debugging); by default `TRUE`
+#' @param debug boolean that allows returning the raw response from the API; by default
+#'  `FALSE`
 #' @param format_type the format to request from the API, one of classic, json, csv; this
-#'  is only used by `fetch_debug`
+#'  is only used by `fetch_debug`, and by default is `"json"`
 #' @return
 #' - For `fetch_args_list`: a `fetch_args` object
 #' @export

README.md

@@ -18,13 +18,12 @@ epicall <- covidcast(
   geo_values = "us",
   time_values = epirange(20210405, 20210410)
 )
-epicall %>% fetch()
 ```
 
 ```
 # A tibble: 6 × 15
   geo_value signal       source   geo_type time_type time_value
-  <chr>     <chr>        <chr>    <fct>    <fct>     <date>    
+  <chr>     <chr>        <chr>    <fct>    <fct>     <date>
 1 us        smoothed_cli fb-surv… nation   day       2021-04-05
 2 us        smoothed_cli fb-surv… nation   day       2021-04-06
 3 us        smoothed_cli fb-surv… nation   day       2021-04-07
@@ -64,8 +63,7 @@ will read by default.
 Note that for the time being, the private endpoints (i.e. those prefixed with
 `pvt`) will require a separate key that needs to be passed as an argument.
 
-
 [mit-image]: https://img.shields.io/badge/License-MIT-yellow.svg
 [mit-url]: https://opensource.org/licenses/MIT
 [github-actions-image]: https://github.com/cmu-delphi/epidatr/workflows/ci/badge.svg
-[github-actions-url]: https://github.com/cmu-delphi/epidatr/actions
+[github-actions-url]: https://github.com/cmu-delphi/epidatr/actions

_pkgdown.yml

@@ -18,6 +18,7 @@ reference:
     desc: Query Delphi Epidata endpoints
   - contents:
       - epidata_call
+      - fetch_args_list
       - covid_hosp_facility
       - covid_hosp_facility_lookup
       - covid_hosp_state_timeseries