improve function documentation, use new has_api_key for exampleesIfme…

…thod

DESCRIPTION

@@ -12,6 +12,7 @@ Depends: R (>= 3.5)
 License: GPL-3
 LazyData: true
 RoxygenNote: 7.3.1
+Roxygen: list(markdown = TRUE)
 Imports:
     httr,
     jsonlite,

NAMESPACE

@@ -1,8 +1,8 @@
 # Generated by roxygen2: do not edit by hand
 
 export(getCensus)
-export(getFunction)
 export(get_api_key)
+export(has_api_key)
 export(listCensusApis)
 export(listCensusMetadata)
 export(makeVarlist)

R/api-key.R

@@ -1,7 +1,14 @@
 #' Retrieve a Census API key stored the .Renivron file
 #'
-#' @returns A CENSUS_KEY or CENSUS_API_KEY value stored in the user's .Renviron.
-#'   file.
+#' @family helpers
+#' @returns A CENSUS_KEY or CENSUS_API_KEY string stored in the user's .Renviron.
+#'   file, or a warning message printed once per R session if none is found.
+#'
+#' @examples
+#' \dontrun{
+#' get_api_key()
+#' }
+#'
 #' @export
 get_api_key <- function() {
 	if (Sys.getenv("CENSUS_KEY") != "") {
@@ -17,3 +24,17 @@ get_api_key <- function() {
 		key
 	}
 }
+#' Is there a saved API token?
+#'
+#' @family helpers
+#' @examples
+#' has_api_key()
+#'
+#' @export
+has_api_key <- function() {
+	if (!is.null(get_api_key())) {
+		TRUE
+	} else {
+		FALSE
+	}
+}

R/datasets.R

@@ -2,7 +2,7 @@
 #'
 #' Some small geographies in some Census APIs can only be used under a state hierarchy.
 #' This is a list of fips codes that may be looped over to retrieve data for all states.
-#' @format A list of fips codes for 50 states and the District of Columbia
+#' @format A list of fips codes for 50 states and the District of Columbia.
 #' @examples
 #' fips
 "fips"

R/getcensus_functions.R

@@ -1,8 +1,6 @@
 #' Internal function: Get the API response, return a data frame
 #'
-#' @param apiurl, key, get, region, time, etc
 #' @keywords internal
-#' @export
 getFunction <- function(apiurl, name, key, get, region, regionin, time, show_call, convert_variables, year, date, period, monthly, category_code, data_type_code, naics, pscode, naics2012, naics2007, naics2002, naics1997, sic, ...) {
 
 	# Return API's built in error message if invalid call
@@ -162,9 +160,8 @@ getFunction <- function(apiurl, name, key, get, region, regionin, time, show_cal
 #' Optional arguments used in some timeseries data APIs.
 #' @param ... Other valid arguments to pass to the Census API. Note: the APIs
 #'   are case sensitive.
-#' @keywords api
-#' @examples
-#' \dontrun{
+#' @returns A data frame with results from the specified U.S. Census Bureau dataset.
+#' @examplesIf has_api_key()
 #' # Get total population and median household income for Census places
 #' # (cities, towns, villages) in a single state from the 5-year American Community Survey.
 #' acs_simple <- getCensus(
@@ -213,7 +210,6 @@ getFunction <- function(apiurl, name, key, get, region, regionin, time, show_cal
 #' 	region = "county:*",
 #' 	NAICS2017 = 23)
 #' head(cbp)
-#' }
 #'
 #' @export
 getCensus <-

R/makevar_functions.R

@@ -4,6 +4,7 @@
 #' a given string. This can be used create a list of variables to later pass to
 #' getCensus, or a data frame documenting variables used in a given project.
 #'
+#' @family metadata
 #' @param name API programmatic name - e.g. acs/acs5. Use `listCensusApis()` to
 #'   see valid dataset names.
 #' @param vintage Vintage (year) of dataset. Not required for timeseries APIs.
@@ -12,9 +13,8 @@
 #'   is "all". Options are "all", "name", "label", or "concept".
 #' @param output Optional argument, specifying output to "list" or "dataframe".
 #'   Default is "list".
-#' @export
-#' @examples
-#' \dontrun{
+#' @returns A data frame containing variable metadata
+#' @examplesIf has_api_key()
 #' # Return a list, and then use getCensus function to retrieve those variables
 #' myvars <- makeVarlist(name = "timeseries/poverty/saipe",
 #'   find = "Ages 0-4",
@@ -25,8 +25,8 @@
 #'   vars = myvars,
 #'   region = "state:*")
 #' head(saipe_dt)
-#' }
-
+#'
+#' @export
 makeVarlist <- function(name, vintage = NULL, find, varsearch = "all", output = "list") {
 	df <- listCensusMetadata(name, vintage, type = "variables")
 	index_name <- with(df, grepl(find, name, ignore.case = T))

R/metadata_functions.R

@@ -1,17 +1,27 @@
 #' Get general information about available datasets
 #'
-#' Scrapes https://api.census.gov/data.json and returns a dataframe that
+#' Scrapes <https://api.census.gov/data.json> and returns a dataframe that
 #' includes columns for dataset title, description, name, vintage, url, dataset
 #' type, and other useful fields.
 #'
-#' @keywords metadata
+#' @family metadata
 #' @param name Optional complete or partial API dataset programmatic name. For
 #'   example, "acs", "acs/acs5", "acs/acs5/subject". If using a partial name,
 #'   this needs to be the left-most part of the dataset name before `/`, e.g.
 #'   "timeseries/eits" or "dec" or "acs/acs5".
 #' @param vintage Optional vintage (year) of dataset.
-#' @examples
-#' \dontrun{
+#' @returns A data frame with the following columns:
+#' * title: Short written description of the dataset.
+#' * name: Programmatic name of the dataset.
+#' * vintage: Year of the survey, for use with microdata and aggregate datasets.
+#' * type: Dataset type, which is either "Aggregate", "Microdata", or "Timeseries".
+#' * temporal: Time period of the dataset. Warning: not always documented.
+#' * spatial: Spatial region of the dataset. Warning: not always documented.
+#' * url: Base URL of the dataset endpoint.
+#' * modified: Date last modified. Warning: sometimes out of date.
+#' * description: Long written description of the dataset.
+#' * contact: Email address for specific questions about the Census Bureau survey.
+#' @examplesIf has_api_key()
 #' # Get information about every dataset available in the APIs
 #' apis <- listCensusApis()
 #' head(apis)
@@ -31,7 +41,6 @@
 #' # Get information about one particular dataset
 #' api_sahie <- listCensusApis(name = "timeseries/healthins/sahie")
 #' head(api_sahie)
-#' }
 #'
 #' @export
 listCensusApis <- function(name = NULL,
@@ -125,20 +134,22 @@ listCensusApis <- function(name = NULL,
 	return(dt)
 }
 
-#' Get metadata about a specific API endpoint, including available variables,
-#' geographies, variable groups, and value labels
+#' Get metadata about a specified API endpoint
 #'
+#' Get information about a Census Bureau API dataset, including its available
+#' variables, geographies, variable groups, and value labels
+#'
+#' @family metadata
 #' @param name API programmatic name - e.g. acs/acs5. Use `listCensusApis()` to
 #'   see valid dataset names.
 #' @param vintage Vintage (year) of dataset. Not required for timeseries APIs.
 #' @param type Type of metadata to return. Options are:
-#'
-#'   * "variables" (default) - list of variable names and descriptions
+#' * "variables" (default) - list of variable names and descriptions
 #'   for the dataset.
-#'   * "geographies" - available geographies.
-#'   * "groups" - available variable groups. Only available
+#' * "geographies" - available geographies.
+#' * "groups" - available variable groups. Only available
 #'   for some datasets.
-#'   * "values" - encoded value labels for a given variable. Pair with
+#' * "values" - encoded value labels for a given variable. Pair with
 #'   "variable_name". Only available for some datasets.
 #' @param group An optional variable group code, used to return metadata for a
 #'   specific group of variables only. Variable groups are not used for all
@@ -148,34 +159,30 @@ listCensusApis <- function(name = NULL,
 #' @param include_values Use with `type = "variables"`. Include value metadata
 #'   for all variables in a dataset if value metadata exists. Default is
 #'   "FALSE".
-#' @keywords metadata
-#' @examples
-#' \dontrun{
-#' # type: variables
-#' # List the variables available in the Small Area Health Insurance Estimates.
+#' @returns A data frame with metadata about the specified API endpoint.
+#' @examplesIf has_api_key()
+#' # type: variables # List the variables available in the Small Area
+#' # Health Insurance Estimates.
 #' variables <- listCensusMetadata(
-#'   name = "timeseries/healthins/sahie",
-#'   type = "variables")
-#'  head(variables)
+#'   name = "timeseries/healthins/sahie", type = "variables")
+#' head(variables)
 #'
 #' # type: variables for a single variable group
 #' # List the variables that are included in the B17020 group in the
 #' # 5-year American Community Survey.
 #' variable_group <- listCensusMetadata(
-#'   name = "acs/acs5",
-#'   vintage = 2022,
-#'   type = "variables",
-#'   group = "B17020")
-#'  head(variable_group)
+#'   name = "acs/acs5", vintage = 2022,
+#'   type = "variables", group = "B17020")
+#' head(variable_group)
 #'
 #' # type: variables, with value labels
-#' # Create a data dictionary with all variable names and encoded values for
-#' # a microdata API.
+#' # Create a data dictionary with all variable names and encoded values
+#' # for a microdata API.
 #' variable_values <- listCensusMetadata(
-#' 	name = "cps/voting/nov",
-#' 	vintage = 2020,
-#' 	type = "variables",
-#' 	include_values = TRUE)
+#'   name = "cps/voting/nov",
+#'   vintage = 2020,
+#'   type = "variables",
+#'   include_values = TRUE)
 #' head(variable_values)
 #'
 #' # type: geographies
@@ -184,25 +191,27 @@ listCensusApis <- function(name = NULL,
 #'   name = "acs/acs5",
 #'   vintage = 2022,
 #'   type = "geographies")
-#'  head(geographies)
+#' head(geographies)
 #'
 #' # type: groups
-#' # List the variable groups available in the 5-year American Community Survey.
+#' # List the variable groups available in the 5-year American
+#' # Community Survey.
 #' groups <- listCensusMetadata(
 #'   name = "acs/acs5",
 #'   vintage = 2022,
 #'   type = "groups")
-#'  head(groups)
+#' head(groups)
 #'
 #' # type: values for a single variable
-#' # List the value labels of the NAICS2017 variable in the County Business Patterns dataset.
+#' # List the value labels of the NAICS2017 variable in the County
+#' # Business Patterns dataset.
 #' naics_values <- listCensusMetadata(
 #'   name = "cbp",
 #'   vintage = 2021,
 #'   type = "values",
 #'   variable = "NAICS2017")
-#'  head(naics_values)
-#' }
+#' head(naics_values)
+#'
 #' @export
 listCensusMetadata <-
 	function(name,

_pkgdown.yaml

@@ -40,6 +40,9 @@ reference:
 - title: "Helpers"
   contents:
   - get_api_key
+  - has_api_key
+- title: "Datasets"
+  contents:
   - fips
 
 redirects: