Better @description in man pages. Addresses partial #48

R/download.R

@@ -11,7 +11,7 @@
 # See the License for the specific language governing permissions and limitations under the License.
 
 
-#' Download a tibble of realtime discharge data from the MSC datamart
+#' Download a tibble of realtime discharge data from the Meteorological Service of Canada datamart
 #'
 #' Download realtime discharge data from the Meteorological Service of Canada (MSC) datamart. The function will prioritize
 #' downloading data collected at the highest resolution. In instances where data is not available at high (hourly or higher) resolution
@@ -196,7 +196,7 @@ realtime_dd <- function(station_number = NULL, prov_terr_state_loc) {
 }
 
 
-#' download a tibble of active realtime stations
+#' Download a tibble of active realtime stations
 #'
 #' An up to date dataframe of all stations in the Realtime Water Survey of Canada 
 #'   hydrometric network operated by Environment and Climate Change Canada
@@ -324,6 +324,7 @@ token_ws <- function(username, password) {
 #' queried depends on other parameters being requested. If one station is requested, 18 
 #' months of data can be requested. If you continually receiving errors when invoking this
 #' function, reduce the number of observations (via station_number, parameters or dates) being requested. 
+#' 
 #' @param station_number Water Survey of Canada station number.
 #' @param parameters parameter ID. Can take multiple entries. Parameter is a numeric code. See \code{param_id} for options. Defaults to all parameters.
 #' @param start_date Need to be in YYYY-MM-DD. Defaults to 30 days before current date. 
@@ -478,13 +479,14 @@ realtime_ws <- function(station_number, parameters = c(46, 16, 52, 47, 8, 5, 41,
   ## Need to output a warning to see if any stations weren't retrieved
 }
 
-#' A function to download hydat
+#' Download and set the path to HYDAT
 #'
-#' Download the hydat sqlite database. This database contains all the historical hydrometric data for Canada's integrated hydrometric network.
+#' Download the HYDAT sqlite database. This database contains all the historical hydrometric data for Canada's integrated hydrometric network.
 #' The function will check for a existing sqlite file and won't download the file if the same version is already present. 
-#' \code{download_hydat} also looks to see if you have the hydat environmental variable set.
+#' \code{download_hydat} also looks to see if you have the HYDAT environmental variable set.
 #'
-#' @param dl_hydat_here Directory to the hydat database. The path is chosen by the \code{rappdirs} package and is OS specific and can be view by \code{rappdirs::user_data_dir}. This path is also supplied automatically to any function that uses the hydat database. A user specified path can be set though this is not the advised approach. 
+#' @param dl_hydat_here Directory to the HYDAT database. The path is chosen by the \code{rappdirs} package and is OS specific and can be view by \code{rappdirs::user_data_dir}. 
+#' This path is also supplied automatically to any function that uses the HYDAT database. A user specified path can be set though this is not the advised approach. 
 #'
 #' @export
 #'

R/hy_annual_stats.R

@@ -13,8 +13,8 @@
 
 #' Extract annual statistics information from the HYDAT database
 #'
-#' Provides wrapper to turn the ANNUAL_STATISTICS table in HYDAT into a tidy data frame. \code{station_number} and
-#'   \code{prov_terr_state_loc} must both be supplied. 
+#' Provides wrapper to turn the ANNUAL_STATISTICS table in HYDAT into a tidy data frame of annual statistics. 
+#' Statistics provided include MEAN, MAX and MIN on an annual basis. 
 #'
 #' @inheritParams hy_stations
 #' @param start_year First year of the returned record

R/hy_daily_flows.R

@@ -12,9 +12,9 @@
 
 #' @title Extract daily flows information from the HYDAT database
 #'
-#' @description Provides wrapper to turn the hy_daily_flows table in HYDAT into a tidy data frame.  \code{station_number} and
-#' \code{prov_terr_state_loc} can both be supplied. If both are omitted all values from the \code{hy_stations} table are returned.
-#' That is a large vector for \code{hy_daily_flows}.
+#' @description Provides wrapper to turn the DLY_FLOWS table in HYDAT into a tidy data frame of daily flows. 
+#' \code{station_number} and \code{prov_terr_state_loc} can both be supplied. If both are omitted all 
+#' values from the \code{hy_stations} table are returned. That is a large tibble for \code{hy_daily_flows}.
 #'
 #' @inheritParams hy_stations
 #' @param start_date Leave blank if all dates are required. Date format needs to be in YYYY-MM-DD. Date is inclusive.

R/hy_daily_levels.R

@@ -12,9 +12,9 @@
 
 #' @title Extract daily levels information from the HYDAT database
 #'
-#' @description Provides wrapper to turn the hy_daily_levels table in HYDAT into a tidy data frame.  \code{station_number} and
-#' \code{prov_terr_state_loc} can both be supplied. If both are omitted all values from the \code{hy_stations} table are returned.
-#' That is a large vector for \code{hy_daily_levels}.
+#' @description Provides wrapper to turn the DLY_LEVELS table in HYDAT into a tidy data frame.  The primary value returned by this 
+#' function is discharge. \code{station_number} and \code{prov_terr_state_loc} can both be supplied. If both are omitted all 
+#' values from the \code{hy_stations} table are returned. That is a large vector for \code{hy_daily_levels}.
 #'
 #' @inheritParams hy_daily_flows
 #'

R/hy_instant_annual_peaks.R

@@ -13,8 +13,8 @@
 
 #' Annual maximum/minimum instantaneous flows and water levels
 #'
-#' Provides wrapper to turn the hy_annual_instant_peaks table in HYDAT into a tidy data frame. \code{station_number} and
-#' \code{prov_terr_state_loc} can both be supplied. 
+#' Provides wrapper to turn the ANNUAL_INSTANT_PEAKS table in HYDAT into a tidy data frame of instantaneous flows and water levels. 
+#' \code{station_number} and \code{prov_terr_state_loc} can both be supplied. 
 #' 
 #' @inheritParams hy_stations
 #' @param start_year First year of the returned record

R/hy_monthly_flows.R

@@ -12,9 +12,9 @@
 
 #' Extract monthly flows information from the HYDAT database
 #'
-#' Provides wrapper to turn the hy_monthly_flows table in HYDAT into a tidy data frame.  \code{station_number} and
-#'   \code{prov_terr_state_loc} can both be supplied. If both are omitted all values from the \code{hy_stations} table are returned.
-#'   That is a large vector for \code{hy_monthly_flows}.
+#' Tidy data of monthly flows information from the DLY_FLOWS HYDAT table. \code{station_number} and
+#' \code{prov_terr_state_loc} can both be supplied. If both are omitted all values from the \code{hy_stations} table are returned.
+#' That is a large vector for \code{hy_monthly_flows}.
 #'
 #' @inheritParams hy_stations
 #' @param start_date Leave blank if all dates are required. Date format needs to be in YYYY-MM-DD. Date is inclusive.

R/hy_monthly_levels.R

@@ -12,7 +12,7 @@
 
 #' Extract monthly levels information from the HYDAT database
 #'
-#' Provides wrapper to turn the hy_monthly_levels table in HYDAT into a tidy data frame.  \code{station_number} and
+#' Tidy data of monthly river or lake levels information from the DLY_LEVELS HYDAT table. \code{station_number} and
 #'   \code{prov_terr_state_loc} can both be supplied. If both are omitted all values from the \code{hy_stations} table are returned.
 #'   That is a large vector for \code{hy_monthly_levels}.
 #'

R/hy_sed_daily_loads.R

@@ -12,9 +12,9 @@
 
 #' Extract daily sediment load information from the HYDAT database
 #'
-#' Provides wrapper to turn the hy_sed_daily_loads table in HYDAT into a tidy data frame.  \code{station_number} and
-#' \code{prov_terr_state_loc} can both be supplied. If both are omitted all values from the \code{hy_stations} table are returned.
-#' That is a large vector for \code{hy_sed_daily_loads}.
+#' Provides wrapper to turn the SED_DLY_LOADS table in HYDAT into a tidy data frame of daily sediment load information.
+#' \code{station_number} and \code{prov_terr_state_loc} can both be supplied. If both are omitted all values from the 
+#' \code{hy_stations} table are returned. That is a large vector for \code{hy_sed_daily_loads}.
 #'
 #' @inheritParams hy_stations
 #' @param start_date Leave blank if all dates are required. Date format needs to be in YYYY-MM-DD. Date is inclusive.

R/hy_sed_daily_suscon.R

@@ -12,9 +12,9 @@
 
 #' Extract daily suspended sediment concentration information from the HYDAT database
 #'
-#' Provides wrapper to turn the hy_sed_daily_suscon table in HYDAT into a tidy data frame.  \code{station_number} and
-#' \code{prov_terr_state_loc} can both be supplied. If both are omitted all values from the \code{hy_stations} table are returned.
-#' That is a large vector for \code{hy_sed_daily_suscon}.
+#' Provides wrapper to turn the SED_DLY_SUSCON table in HYDAT into a tidy data frame of daily suspended sediment concentration information.
+#' \code{station_number} and \code{prov_terr_state_loc} can both be supplied. If both are omitted all values from the \code{hy_stations} 
+#' table are returned. That is a large vector for \code{hy_sed_daily_suscon}.
 #'
 #' @inheritParams hy_daily_flows
 #'

R/hy_sed_monthly_loads.R

@@ -12,7 +12,7 @@
 
 #' Extract monthly flows information from the HYDAT database
 #'
-#' Provides wrapper to turn the hy_sed_monthly_loads table in HYDAT into a tidy data frame.  \code{station_number} and
+#' Tidy data of monthly loads information from the SED_DLY_LOADS HYDAT table. \code{station_number} and
 #'   \code{prov_terr_state_loc} can both be supplied. If both are omitted all values from the \code{hy_stations} table are returned.
 #'   That is a large vector for \code{hy_sed_monthly_loads}.
 #'

R/hy_sed_monthly_suscon.R

@@ -12,7 +12,7 @@
 
 #' Extract monthly flows information from the HYDAT database
 #'
-#' Provides wrapper to turn the hy_sed_monthly_suscon table in HYDAT into a tidy data frame.  \code{station_number} and
+#' Tidy data of monthly suspended sediment concentration information from the SED_DLY_SUSCON HYDAT table.  \code{station_number} and
 #'   \code{prov_terr_state_loc} can both be supplied. If both are omitted all values from the \code{hy_stations} table are returned.
 #'   That is a large vector for \code{hy_sed_monthly_suscon}.
 #'

R/hy_sed_samples.R

@@ -12,9 +12,9 @@
 
 #' Extract instantaneous sediment sample information from the HYDAT database
 #'
-#' Provides wrapper to turn the hy_sed_samples table in HYDAT into a tidy data frame.  \code{station_number} and
-#' \code{prov_terr_state_loc} can both be supplied. If both are omitted all values from the \code{hy_stations} table are returned.
-#' That is a large vector for \code{hy_sed_samples}.
+#' Provides wrapper to turn the hy_sed_samples table in HYDAT into a tidy data frame of instantaneous sediment sample information.  
+#' \code{station_number} and \code{prov_terr_state_loc} can both be supplied. If both are omitted all values from the \code{hy_stations} 
+#' table are returned. That is a large vector for \code{hy_sed_samples}.
 #'
 #' @inheritParams hy_stations
 #' @param start_date Leave blank if all dates are required. Date format needs to be in YYYY-MM-DD. Date is inclusive.

R/hy_sed_samples_psd.R

@@ -10,11 +10,11 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and limitations under the License.
 
-#' Extract instantaneous sediment sample information from the HYDAT database
+#' Extract instantaneous sediment sample particle size distribution information from the HYDAT database
 #'
-#' Provides wrapper to turn the hy_sed_samples_psd table in HYDAT into a tidy data frame.  \code{station_number} and
-#' \code{prov_terr_state_loc} can both be supplied. If both are omitted all values from the \code{hy_stations} table are returned.
-#' That is a large vector for \code{hy_sed_samples_psd}.
+#' Provides wrapper to turn the hy_sed_samples_psd table in HYDAT into a tidy data frame of instantaneous sediment sample 
+#' particle size distribution.  \code{station_number} and \code{prov_terr_state_loc} can both be supplied. If both 
+#' are omitted all values from the \code{hy_stations} table are returned. That is a large vector for \code{hy_sed_samples_psd}.
 #'
 #' @inheritParams hy_stations
 #' @param start_date Leave blank if all dates are required. Date format needs to be in YYYY-MM-DD. Date is inclusive.

R/hy_stations.R

@@ -14,8 +14,10 @@
 
 #' Extract station information from the HYDAT database
 #'
-#' Provides wrapper to turn the hy_stations table in HYDAT into a tidy data frame. \code{station_number} and
-#' \code{prov_terr_state_loc} can both be supplied. If both are omitted all values from the \code{hy_stations} table are returned
+#' Provides wrapper to turn the hy_stations table in HYDAT into a tidy data frame of station information. \code{station_number} and
+#' \code{prov_terr_state_loc} can both be supplied. If both are omitted all values from the \code{hy_stations} table are returned. This
+#' is the entry point for most analyses is tidyhydat as establish the stations for consideration is likely the first step in many
+#' instances. 
 #'
 #' @inheritParams hy_agency_list
 #' @param station_number A seven digits Water Survey of Canada station number. If this argument is omitted, the value of \code{prov_terr_state_loc}

R/hy_stn_regulation.R

@@ -14,8 +14,9 @@
 
 #' Extract station regulation from the HYDAT database
 #'
-#' Provides wrapper to turn the hy_stn_regulation table in HYDAT into a tidy data frame. \code{station_number} and
-#' \code{prov_terr_state_loc} can both be supplied. If both are omitted all values from the \code{hy_stations} table are returned
+#' Provides wrapper to turn the hy_stn_regulation table in HYDAT into a tidy data frame of station regulation. 
+#' \code{station_number} and \code{prov_terr_state_loc} can both be supplied. If both are omitted all values 
+#' from the \code{hy_stations} table are returned.
 #'
 #' @inheritParams hy_stations
 #'

R/tidyhydat.R

@@ -11,28 +11,46 @@
 # See the License for the specific language governing permissions and limitations under the License.
 
 
-
-#' Extract tidy river data
+#' Extract tidy water data
 #'
-#' tidyhydat provides functions to extract river data from Water Survey of Canada sources and make it tidy.
+#' @description tidyhydat provides a series of functions to make downloading and importing data from HYDAT into R a 
+#' simple process for a user. HYDAT is the Canada national water data archive, plublished quarterly by 
+#' the Government of Canada's Department of Environment and Climate Change. It is relational database that 
+#' contains daily, monthly and annual data on water flow, water levels and sediment data. Functions are also 
+#' provided to extract station metadata like position and record history.
+#' 
+#' In addition to historical data from HYDAT, tidhydat also provide functions to access realtime water flow and 
+#' water level data. This data is raw and unapproved originating directly from the station. 
+#' 
+#' Regardless of the data source, tidyhydat organizes all this data in a consistent format that allows the user to 
+#' quickly and efficient connect with Canadian hydrological data. 
 #'
 #'
 #' @docType package
 #' @name tidyhydat
 #' 
 #' @importFrom dplyr %>%
 #'
-#' @references For more information on tidy data please see
+#' @references 
+#' 
+#' To download the latest version of hydat please:
+#'  \itemize{
+#'   \item use the \code{download_hydat()} function.
+#'   }
+#' 
+#' For more information on tidy data please see
 #' \itemize{
 #'  \item Wickham, Hadley. 2014. Tidy Data. The Journal of Statistical Software. 59. \url{https://www.jstatsoft.org/article/view/v059i10}
 #'  \item tidy data vignette: \url{https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html}
 #'  }
 #'
-#'  To download the latest version of hydat please either:
+#'  For more information on HYDAT 
 #'  \itemize{
-#'   \item Follow this link \url{http://collaboration.cmc.ec.gc.ca/cmc/hydrometrics/www/} or;
-#'   \item use the \code{download_hydat()} function.
-#'   }
-#'   
+#'    \item Please see this description of the database: goo.gl/H3NXJQ
+#'    \item This page is landing page for technical description of HYDAT:
+#'    \url{http://collaboration.cmc.ec.gc.ca/cmc/hydrometrics/www/}
+#'    \item This page links to a document that outlines database table definitions:
+#'    \url{http://collaboration.cmc.ec.gc.ca/cmc/hydrometrics/www/HYDAT_Definition_EN.pdf}
+#'    }
 #'
 NULL