Merge pull request #172 from cmu-delphi/cranChecklist

Cran checklist

Author: dsweber2

.github/workflows/pkgdown.yaml

@@ -5,9 +5,9 @@
 # update the documentation web site on pushes to `dev` branch.
 on:
   push:
-    branches: [main, master, dev]
+    branches: [main]
   pull_request:
-    branches: [main, master, dev]
+    branches: [main]
   release:
     types: [published]
   workflow_dispatch:

DESCRIPTION

@@ -17,7 +17,7 @@ Authors@R:
   )
 URL: https://cmu-delphi.github.io/epidatr/, https://github.com/cmu-delphi/epidatr
 BugReports: https://github.com/cmu-delphi/epidatr/issues
-Description: R Client for Delphi's 'Epidata' API. Tools for fetching data in various forms.
+Description: The Delphi 'Epidata' API provides real-time access to epidemiological surveillance data for influenza, COVID-19, and other diseases for the USA at various geographical resolutions, both from official government sources such as the Center for Disease Control (CDC) and Google Trends and private partners such as Facebook and Change Healthcare. It is built and maintained by the Carnegie Mellon University Delphi research group.
 Depends: R (>= 3.5.0)
 License: MIT + file LICENSE
 Encoding: UTF-8

R/auth.R

@@ -1,9 +1,10 @@
-#' Get the API key
+#' Getting the API key
 #'
+#' @description
 #' Get the API key from the environment variable `DELPHI_EPIDATA_KEY` or
 #' `getOption("delphi.epidata.key")`.
 #'
-#' @return The API key
+#' @return The API key as a string or "".
 #'
 #' @export
 get_auth_key <- function() {

R/avail_endpoints.R

@@ -1,13 +1,16 @@
-#' List all available endpoints
+#' List all available endpoints.
 #'
-#' @return A [`tibble::tibble`] with 2 columns. `Endpoint` contains the function
-#'   for accessing the Delphi Epidata API endpoint along with a `Description`.
+#' @description
+#' A function that prints a tibble with two columns: `Endpoint` contains the
+#' function for accessing the Delphi Epidata API endpoint along with a
+#' `Description`.
+#'
+#' @return A [`tibble::tibble`].
 #' @export
 #' @importFrom utils help.search
 #'
 #' @examples
-#' endps <- avail_endpoints()
-#' print(endps, n = nrow(endps))
+#' avail_endpoints()
 avail_endpoints <- function() {
   h <- help.search("endpoint",
     package = "epidatr", fields = "concept",

R/cache.R

@@ -216,9 +216,11 @@ disable_cache <- function() {
 }
 
 #' Describe current cache
+#'
 #' @description
 #' Print out the information about the cache (as would be returned by cachem's
-#' `info()` method)
+#' `info()` method).
+#'
 #' @seealso [`set_cache`] to start a new cache (and general caching info),
 #'   [`clear_cache`] to delete the cache and set a new one, and [`disable_cache`] to
 #'   disable without deleting
@@ -234,7 +236,7 @@ cache_info <- function() {
 #' Dispatch caching
 #'
 #' @description
-#' the guts of caching, its interposed between fetch and the specific fetch
+#' The guts of caching, its interposed between fetch and the specific fetch
 #' methods. Internal method only.
 #'
 #' @param call the `epidata_call` object

R/covidcast.R

@@ -96,10 +96,39 @@ print.covidcast_data_source <- function(x, ...) {
 }
 
 #' Creates the COVIDcast Epidata autocomplete helper
-#'
+#' @description
 #' Creates a helper object that can use auto-complete to help find COVIDcast
-#' sources and signals.
+#' sources and signals. 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 <- 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`
+#' ```
+#'
+#' These objects can be used directly to fetch data, without requiring us to use
+#' the `covidcast()` function. Simply use the `$call` attribute of the object:
 #'
+#' ```{r}
+#' epidata$signals$`fb-survey:smoothed_cli`$call("state", "pa",
+#'                                               epirange(20210405, 20210410))
+#' ```
 #' @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