docs: Adds details to attend issues #295, #287, #221, #199

[JavierMtzRdz]

Checklist

Please:

• Make sure this PR is against "dev", not "main" (unless this is a release
  PR).
• Request a review from one of the current epidatr main reviewers:
  brookslogan, dshemetov, nmdefries, dsweber2.
• Makes sure to bump the version number in DESCRIPTION. Always increment
  the patch version number (the third number), unless you are making a
  release PR from dev to main, in which case increment the minor version
  number (the second number).
• Describe changes made in NEWS.md, making sure breaking changes
  (backwards-incompatible changes to the documented interface) are noted.
  Collect the changes under the next release number (e.g. if you are on
  1.7.2, then write your changes under the 1.8 heading).

Change explanations for reviewer

• Issue docs: auth keys instructions #295: Description for save_api_key is inaccurate.

• Change: Provide a clearer explanation as in the message linked to the function.

• Issue Small function documentation details updates #287: The pvt_meta_norostat locations parameter lacks valid inputs.

• Change: Provides a clearer explanation.

• Issue Reduce doc duplication in general and for version-related params #221: Reduce duplication

• Change: Adds a .epidatr_shared_params list of parameters that includes shared parameters and inherits shared parameters in the specific functions' documentation.

• Issue document versions, issues, as_of, and recommendations #199: Group as_of, issues, and lag

• Change: Adds a Data Versioning section to clarify its use.

Magic GitHub syntax to mark associated Issue(s) as resolved when this is merged into the default branch

• Resolves docs: auth keys instructions #295, resolves Small function documentation details updates #287, resolves Reduce doc duplication in general and for version-related params #221, resolves document versions, issues, as_of, and recommendations #199

[dshemetov]

praise: Thanks for taking these issues on!

question: Does R intelligently notice when a "shared parameter" isn't present in a function and leave it off? If yes, then consolidating all params up here sounds great. If not, then will this list arguments that don't apply to various endpoints? For instance, pub_covidcast doesn't have regions or states or locations, do those still show up? It might not be a big deal if there are extra arguments, just wondering what our options are for this sort of thing.

[JavierMtzRdz]

answer: Yes, "@inheritParams only inherits docs for arguments that the function actually uses and that aren’t already documented". Also, there are a few cases where epiweeks or regions have a different description. In those cases, roxygen2 overrides the inherited parameter description with the provided description for that function.

Also, I reviewed the documentation to ensure it was working as intended, and it is. pub_fluview_clinical as an example below.

[brookslogan]

issue: for fluview_clinical regions, I don't see the link to the full region list.

suggestion: make fluview and fluview_clinical regions description more specific. E.g., I think something like

#' @param regions character. Vector of location IDs to fetch.  Can be
#'   "nat" for national, "hhs1"--"hhs10" for HHS Regions, "cen1"--"cen9" for census divisions,
#'   lowercase two-letter state or territory abbreviations for most states and territories,
#'   "jfk" for New York City, or "ny_minus_jfk" for upstate New York.
#'   Full list of locations is available <here>.

w/ an actual link.

[JavierMtzRdz]

fixed: I incorporated the detailed description you proposed. Regarding the link, I wanted to create a section within the Epidata API Documentation website, but while that is being arranged, I linked it to the regions' labels in the repository.

[brookslogan]

todo: fix content that got cut off here

[JavierMtzRdz]

Fixed!

[JavierMtzRdz]

I added changes to address issues #208 and #288.

Change explanations for reviewer

• Issue Consider changing \dontrun in examples to \donttest #208: \dontrun does not permit examples showing request outputs on the documentation site. It suggests using \donttest.

• Change: I added conditional examples with @examplesIf so they only run when there is internet access and the corresponding API key is available. I did not use \donttest as it is checked by CRAN occasionally. The examples on the documentation website appear when the API key is available. Examples with lengthy outputs are enclosed within \dontrun safeguards.

• Issue Audit all endpoint examples to make sure they actually run as-is #288: Audit all endpoint examples.

• Note: All examples worked. The only relevant comment is that the pub_flusurv example returns data with a warning.

Warning message:
Not all return columns are specified as expected epidata fields
ℹ Unspecified fields season, rate_age_5, rate_age_6, rate_age_7, rate_age_18t29,
rate_age_30t39, rate_age_40t49, rate_age_5t11, rate_age_12t17, rate_age_lt18,
rate_age_gte18, rate_age_1t4, rate_age_gte75, rate_age_0tlt1, rate_race_white,
rate_race_black, rate_race_hisp, rate_race_asian, …, rate_flu_a, and rate_flu_b may
need to be manually converted to more appropriate classes

Magic GitHub syntax to mark associated Issue(s) as resolved when this is merged into the default branch

• Resolves Consider changing \dontrun in examples to \donttest #208, resolves Audit all endpoint examples to make sure they actually run as-is #288

[dshemetov]

Request: the Data Versioning section is good, but can we also add two more examples to the Getting Started vignette to address my suggestion in #199? Specifically of using the issues field and the lag field.