improve ncdc docs, more info on token usage, added @family

to provide better navigation links in all of the ncdc* man files
bumped dev version

DESCRIPTION

@@ -7,7 +7,7 @@ Description: Client for many 'NOAA' data sources including the 'NCDC' climate
     for 'NOAA' sea ice data, the 'NOAA' severe weather inventory, 'NOAA' Historical
     Observing 'Metadata' Repository ('HOMR') data, 'NOAA' storm data via 'IBTrACS',
     tornado data via the 'NOAA' storm prediction center, and more.
-Version: 0.6.0.9333
+Version: 0.6.0.9335
 License: MIT + file LICENSE
 Encoding: UTF-8
 Authors@R: c(

R/ncdc.r

@@ -3,6 +3,7 @@
 #' @export
 #' @template rnoaa
 #' @template noaa
+#' @template token
 #' @param stationid Accepts a valid station id or a vector or list of station ids
 #' @param includemetadata Used to improve response time by preventing the calculation of
 #' result metadata. Default: TRUE. This does not affect the return object, in that the named part
@@ -43,6 +44,8 @@
 #' The meta slot is a list of metadata elements, and the data slot is a data.frame,
 #' possibly of length zero if no data is found.
 #'
+#' @family ncdc
+#'
 #' @examples \dontrun{
 #' # GHCN-Daily (or GHCND) data, for a specific station
 #' ncdc(datasetid='GHCND', stationid='GHCND:USW00014895', startdate = '2013-10-01',

R/ncdc_combine.r

@@ -4,6 +4,7 @@
 #'
 #' @param ... Objects from another ncdc_* function.
 #' @return A data.frame
+#' @family ncdc
 #' @examples \dontrun{
 #' # data
 #' out1 <- ncdc(datasetid='GHCND', locationid = 'FIPS:02', startdate = '2010-05-01',

R/ncdc_datacats.r

@@ -4,11 +4,13 @@
 #'
 #' @export
 #' @template datacats
+#' @template token
 #' @template all
 #' @return A \code{data.frame} for all datasets, or a list of length two, each
 #'    with a data.frame.
 #' @details Note that calls with both startdate and enddate don't seem to work, though specifying
 #'    one or the other mostly works.
+#' @family ncdc
 #' @examples \dontrun{
 #' ## Limit to 10 results
 #' ncdc_datacats(limit=10)

R/ncdc_datasets.r

@@ -8,10 +8,14 @@
 #' @template rnoaa
 #' @template rnoaa2
 #' @template datasets
-#' @param datasetid (optional) Accepts a single valid dataset id. Data returned will be
-#'    from the dataset specified.
-#' @param stationid Accepts a valid station id or a vector or list of station ids
-#' @return A data.frame for all datasets, or a list of length two, each with a data.frame.
+#' @template token
+#' @param datasetid (optional) Accepts a single valid dataset id. Data returned
+#' will be from the dataset specified.
+#' @param stationid Accepts a valid station id or a vector or list of station
+#' ids
+#' @return A data.frame for all datasets, or a list of length two, each with
+#' a data.frame.
+#' @family ncdc
 #' @examples \dontrun{
 #' # Get a table of all datasets
 #' ncdc_datasets()

R/ncdc_datatypes.r

@@ -1,20 +1,24 @@
 #' Get possible data types for a particular dataset
 #'
-#' From the NOAA API docs: Describes the type of data, acts as a label. If it's 64
-#' degrees out right now, then the data type is Air Temperature and the data is 64.
+#' From the NOAA API docs: Describes the type of data, acts as a label.
+#' For example: If it's 64 degrees out right now, then the data type is
+#' Air Temperature and the data is 64.
 #'
 #' @export
 #' @template rnoaa
 #' @template rnoaa2
 #' @template datatypes
-#' @param datasetid (optional) Accepts a valid dataset id or a vector or list of them. Data
-#'    returned will be from the dataset specified.
-#' @param stationid Accepts a valid station id or a vector or list of station ids
-#' @param datacategoryid Optional. Accepts a valid data category id or a vector or list
-#'    of data category ids (although it is rare to have a data type with more than
-#'    one data category)
-#' @return A \code{data.frame} for all datasets, or a list of length two, each with
-#'    a data.frame.
+#' @template token
+#' @param datasetid (optional) Accepts a valid dataset id or a vector or list
+#' of them. Data returned will be from the dataset specified.
+#' @param stationid Accepts a valid station id or a vector or list of
+#' station ids
+#' @param datacategoryid Optional. Accepts a valid data category id or a vector
+#' or list of data category ids (although it is rare to have a data type with
+#' more than one data category)
+#' @return A \code{data.frame} for all datasets, or a list of length two,
+#' each with a data.frame
+#' @family ncdc
 #' @examples \dontrun{
 #' # Fetch available data types
 #' ncdc_datatypes()

R/ncdc_locs.r

@@ -1,13 +1,16 @@
 #' Get metadata about NOAA NCDC locations.
 #'
-#' From the NOAA NCDC API docs: Locations can be a specific latitude/longitude point
-#' such as a station, or a label representing a bounding area such as a city.
+#' From the NOAA NCDC API docs: Locations can be a specific latitude/longitude
+#' point such as a station, or a label representing a bounding area such as
+#' a city.
 #'
 #' @export
 #'
 #' @template location
+#' @template token
 #' @param locationid A valid location id or a vector or list of location ids.
 #' @return A list containing metadata and the data, or a single data.frame.
+#' @family ncdc
 #' @examples \dontrun{
 #' # All locations, first 25 results
 #' ncdc_locs()

R/ncdc_locs_cats.r

@@ -8,7 +8,9 @@
 #' @export
 #'
 #' @template location
+#' @template token
 #' @return A list containing metadata and the data, or a single data.frame.
+#' @family ncdc
 #' @examples \dontrun{
 #' # All location categories, first 25 results
 #' ncdc_locs_cats()

R/ncdc_plot.r

@@ -8,6 +8,7 @@
 #' @param dateformat Date format using standard POSIX specification for labels on
 #' x-axis. See \code{\link{date_format}}
 #' @return ggplot2 plot
+#' @family ncdc
 #' @details
 #' This function accepts directly output from the \code{\link[rnoaa]{ncdc}} function,
 #' not other functions.

R/ncdc_stations.r

@@ -1,19 +1,22 @@
 #' Get metadata about NOAA NCDC stations.
 #'
-#' From the NOAA NCDC API docs: Stations are where the data comes from (for most datasets)
-#' and can be considered the smallest granual of location data. If you know what
-#' station you want, you can quickly get all manner of data from it
+#' From the NOAA NCDC API docs: Stations are where the data comes from
+#' (for most datasets) and can be considered the smallest granual of location
+#' data. If you know what station you want, you can quickly get all manner of
+#' data from it
 #'
 #' @export
 #'
 #' @template rnoaa
 #' @template rnoaa2
 #' @template stations
-#' @param datasetid (optional) Accepts a valid dataset id or a vector or list of them. Data
-#'    returned will be from the dataset specified.
+#' @template token
+#' @param datasetid (optional) Accepts a valid dataset id or a vector or
+#' list of them. Data returned will be from the dataset specified.
 #' @param stationid A single valid station id, with datasetid namespace,
 #' e.g., GHCND:USW00014895
 #' @return A list of metadata.
+#' @family ncdc
 #' @examples \dontrun{
 #' # Get metadata on all stations
 #' ncdc_stations()

man-roxygen/datacats.r

@@ -14,13 +14,6 @@
 #' @param limit Defaults to 25, limits the number of results in the response. Maximum is
 #'    1000 (optional)
 #' @param offset Defaults to 0, used to offset the resultlist (optional)
-#' @param token This must be a valid token token supplied to you by NCDC's Climate
-#'    Data Online access token generator. (required) Get an API key (=token) at
-#'    http://www.ncdc.noaa.gov/cdo-web/token. You can pass your token in as
-#'    an argument or store it in your .Rprofile file with an entry like
-#'    \itemize{
-#'      \item options("noaakey" = "your-noaa-token")
-#'    }
 #' @param ... Further named parameters, such as \code{query}, \code{path}, etc, passed on to
 #' \code{\link[httr]{modify_url}}. Unnamed parameters will be combined with
 #' \code{\link[httr]{config}}.

man-roxygen/location.r

@@ -11,13 +11,6 @@
 #' @param limit Defaults to 25, limits the number of results in the response. Maximum is
 #'    1000 (optional)
 #' @param offset Defaults to 0, used to offset the resultlist (optional)
-#' @param token This must be a valid token token supplied to you by NCDC's Climate
-#'    Data Online access token generator. (required) Get an API key (=token) at
-#'    http://www.ncdc.noaa.gov/cdo-web/token. You can pass your token in as
-#'    an argument or store it in your .Rprofile file with an entry like
-#'    \itemize{
-#'      \item options("noaakey" = "your-noaa-token")
-#'    }
 #' @param ... Further named parameters, such as \code{query}, \code{path}, etc, passed on to
 #' \code{\link[httr]{modify_url}}. Unnamed parameters will be combined with
 #' \code{\link[httr]{config}}.

man-roxygen/rnoaa.r

@@ -8,11 +8,4 @@
 #' @param limit Defaults to 25, limits the number of results in the response. Maximum is
 #'    1000 (optional)
 #' @param offset Defaults to 0, used to offset the resultlist (optional)
-#' @param token This must be a valid token token supplied to you by NCDC's Climate
-#'    Data Online access token generator. (required) Get an API key (=token) at
-#'    http://www.ncdc.noaa.gov/cdo-web/token. You can pass your token in as
-#'    an argument or store it in your .Rprofile file with an entry like
-#'    \itemize{
-#'      \item options("noaakey" = "your-noaa-token")
-#'    }
 #' @param ... Curl options passed on to \code{\link[httr]{GET}} (optional)

man-roxygen/token.R

@@ -0,0 +1,18 @@
+#' @param token This must be a valid token token supplied to you by NCDC's
+#' Climate Data Online access token generator. (required) See
+#' \strong{Authentication} section below for more details.
+#'
+#' @section Authentication:
+#' Get an API key (aka, token) at \url{http://www.ncdc.noaa.gov/cdo-web/token}.
+#' You can pass your token in as an argument or store it one of two places:
+#'
+#' \itemize{
+#'   \item your .Rprofile file with an entry like
+#'   \code{options(noaakey = "your-noaa-token")}
+#'   \item your .Renviron file with an entry like
+#'   \code{NOAA_KEY=your-noaa-token}
+#' }
+#'
+#' See \code{\link{Startup}} for information on how to create/find your
+#' .Rrofile and .Renviron files
+