Make the autocomplete helper public and document it better

Author: capnrefsmmat

NAMESPACE

@@ -10,6 +10,7 @@ export(covid_hosp_facility)
 export(covid_hosp_facility_lookup)
 export(covid_hosp_state_timeseries)
 export(covidcast)
+export(covidcast_epidata)
 export(covidcast_meta)
 export(delphi)
 export(dengue_nowcast)

R/covidcast.R

@@ -87,18 +87,18 @@ print.covidcast_data_source <- function(x, ...) {
   print(signals[, c("signal", "name", "short_description")], ...)
 }
 
-#' creates the covidcast epidata helper
+#' Creates the COVIDcast Epidata autocomplete helper
 #'
-#' Creates a helper object that can use auto-complete to help find covidcast
+#' Creates a helper object that can use auto-complete to help find COVIDcast
 #' sources and signals.
 #'
 #' @param base_url optional alternative API base url
 #' @param timeout_seconds the maximum amount of time to wait for a response
 #' @importFrom httr stop_for_status content http_type
 #' @importFrom jsonlite fromJSON
 #' @importFrom xml2 read_html xml_find_all xml_text
-#' @return an instance of covidcast_epidata
-#'
+#' @return An instance of `covidcast_epidata`
+#' @export
 covidcast_epidata <- function(base_url = global_base_url, timeout_seconds = 30) {
   url <- join_url(base_url, "covidcast/meta")
   response <- do_request(url, list(), timeout_seconds)

man/covidcast_epidata.Rd

@@ -62,17 +62,33 @@ Examples queries with all the endpoint functions available in this package are g
 
 ## Advanced Usage (Experimental)
 
-You can use `covidcast_epidata` to get help with finding sources and functions without leaving R.
-Using tab completion after typing `epidata$signals$` below, you can see all the available sources and signals in the API, with the format `source:signal`.
-Note that some signal names have dashes in them, so to access them we rely on the backtick operator.
+The [COVIDcast
+endpoint](https://cmu-delphi.github.io/delphi-epidata/api/covidcast.html) of the
+Epidata API contains many separate data sources and signals. It can be difficult
+to find the name of the signal you're looking for, so you can use
+`covidcast_epidata` to get help with finding sources and functions without
+leaving R.
+
+The `covidcast_epidata()` function fetches a list of all signals, and returns an
+object containing fields for every signal:
 
 ```{r}
-epidata <- epidatr:::covidcast_epidata()
+epidata <- covidcast_epidata()
 epidata$signals
+```
+
+If you use an editor that supports tab completion, such as RStudio, type
+`epidata$signals$` and wait for the tab completion popup. You will be able to
+type the name of signals and have the autocomplete feature select them from the
+list for you. Note that some signal names have dashes in them, so to access them
+we rely on the backtick operator:
+
+```{r}
 epidata$signals$`fb-survey:smoothed_cli`
 ```
 
-From there, you can construct a call analogous to the one above, but using the API object instead of the functions directly.
+These objects can be used directly to fetch data, without requiring us to use
+the `covidcast()` function. Simple use the `$call` attribute of the object:
 
 ```{r}
 epicall <- epidata$signals$`fb-survey:smoothed_cli`$call("state", "pa", epirange(20210405, 20210410))