Merge pull request #114 from Public-Health-Scotland/cran/documentatio…

…n-return-values

Update the documentation

DESCRIPTION

@@ -32,7 +32,6 @@ Imports:
     lifecycle,
     lubridate,
     magrittr,
-    purrr,
     readr,
     rlang,
     scales (>= 1.0.0),
@@ -50,3 +49,4 @@ Encoding: UTF-8
 Language: en-GB
 LazyData: true
 RoxygenNote: 7.2.3
+Roxygen: list(markdown = TRUE)

R/age_calculate.R

@@ -1,17 +1,23 @@
 #' Calculate age between two dates
 #'
-#' @description This function calculates the age between two dates using functions in \code{lubridate}.
-#' It calculates age in either years or months.
+#' @description This function calculates the age between two dates using
+#' functions in `lubridate`. It calculates age in either years or months.
 #'
-#' @param start A start date (e.g. date of birth) which must be supplied with \code{Date} or \code{POSIXct} or \code{POSIXlt}
-#' class. \code{\link[base:as.Date]{as.Date()}},
-#' \code{\link[lubridate:ymd]{lubridate::dmy()}} and
-#' \code{\link[base:as.POSIXlt]{as.POSIXct()}} are examples of functions which
+#' @param start A start date (e.g. date of birth) which must be supplied with
+#' `Date` or `POSIXct` or `POSIXlt`
+#' class. [base::as.Date()],
+#' [`lubridate::dmy()`][lubridate::ymd] and
+#' [`as.POSIXct()`][base::as.POSIXlt] are examples of functions which
 #' can be used to store dates as an appropriate class.
-#' @param end An end date which must be supplied with \code{Date} or \code{POSIXct} or \code{POSIXlt} class.
-#' Default is \code{Sys.Date()} or \code{Sys.time()} depending on the class of \code{start}.
-#' @param units Type of units to be used. years and months are accepted. Default is \code{years}.
-#' @param round_down Should returned ages be rounded down to the nearest whole number. Default is \code{TRUE}.
+#' @param end An end date which must be supplied with `Date` or `POSIXct` or
+#' `POSIXlt` class. Default is `Sys.Date()` or `Sys.time()` depending on the
+#' class of `start`.
+#' @param units Type of units to be used. years and months are accepted.
+#' Default is `years`.
+#' @param round_down Should returned ages be rounded down to the nearest whole
+#' number. Default is `TRUE`.
+#'
+#' @return A numeric vector representing the ages in the given units.
 #'
 #' @examples
 #' library(lubridate)
@@ -20,17 +26,25 @@
 #' age_calculate(birth_date, end_date)
 #' age_calculate(birth_date, end_date, units = "months")
 #'
-#' # If the start day is leap day (February 29th), age increases on 1st March every year.
+#' # If the start day is leap day (February 29th), age increases on 1st March
+#' # every year.
 #' leap1 <- lubridate::ymd("2020-02-29")
 #' leap2 <- lubridate::ymd("2022-02-28")
 #' leap3 <- lubridate::ymd("2022-03-01")
 #'
 #' age_calculate(leap1, leap2)
 #' age_calculate(leap1, leap3)
 #' @export
-age_calculate <- function(start, end = if (lubridate::is.Date(start)) Sys.Date() else Sys.time(),
-                          units = c("years", "months"), round_down = TRUE) {
-  make_inheritance_checks(list(start = start, end = end), target_classes = c("Date", "POSIXt"), ignore_null = FALSE)
+age_calculate <- function(
+    start,
+    end = if (lubridate::is.Date(start)) Sys.Date() else Sys.time(),
+    units = c("years", "months"),
+    round_down = TRUE) {
+  make_inheritance_checks(
+    list(start = start, end = end),
+    target_classes = c("Date", "POSIXt"),
+    ignore_null = FALSE
+  )
 
   units <- match.arg(tolower(units), c("years", "months"))
 

R/chi_check.R

@@ -1,7 +1,7 @@
 #' @title Check the validity of a CHI number
 #'
-#' @description \code{chi_check} takes a CHI number or a vector of CHI numbers
-#' with \code{character} class. It returns feedback on the validity of the
+#' @description `chi_check` takes a CHI number or a vector of CHI numbers
+#' with `character` class. It returns feedback on the validity of the
 #' entered CHI number and, if found to be invalid, provides an explanation as
 #' to why.
 #'
@@ -16,44 +16,46 @@
 #' even for female. The tenth digit is a check digit, denoted `checksum`.
 #'
 #' While a CHI number is made up exclusively of numeric digits, it cannot be
-#' stored with \code{numeric} class in R. This is because leading zeros in
+#' stored with `numeric` class in R. This is because leading zeros in
 #' numeric values are silently dropped, a practice not exclusive to R. For this
-#' reason, \code{chi_check} accepts input values of \code{character} class
+#' reason, `chi_check` accepts input values of `character` class
 #' only. A leading zero can be added to a nine-digit CHI number using
-#' \code{\link{chi_pad}}.
+#' [chi_pad()].
 #'
-#' \code{chi_check} assesses whether an entered CHI number is valid by checking
+#' `chi_check` assesses whether an entered CHI number is valid by checking
 #' whether the answer to each of the following criteria is `Yes`:
 #'
-#' \itemize{
-#' \item Does it contain no non-numeric characters?
-#' \item Is it ten digits in length?
-#' \item Do the first six digits denote a valid date?
-#' \item Is the checksum digit correct?
-#' }
+#' * Does it contain no non-numeric characters?
+#' * Is it ten digits in length?
+#' * Do the first six digits denote a valid date?
+#' * Is the checksum digit correct?
 #'
-#' @param x a CHI number or a vector of CHI numbers with \code{character} class.
+#' @param x a CHI number or a vector of CHI numbers with `character` class.
 #'
-#' @return \code{chi_check} returns a character string. Depending on the
+#' @return `chi_check` returns a character string. Depending on the
 #' validity of the entered CHI number, it will return one of the following:
 #'
-#' \itemize{
-#' \item `Valid CHI`
-#' \item `Invalid character(s) present`
-#' \item `Too many characters`
-#' \item `Too few characters`
-#' \item `Invalid date`
-#' \item `Invalid checksum`
-#' \item `Missing (NA)`
-#' \item `Missing (Blank)`
-#' }
+#' * `Valid CHI`
+#' * `Invalid character(s) present`
+#' * `Too many characters`
+#' * `Too few characters`
+#' * `Invalid date`
+#' * `Invalid checksum`
+#' * `Missing (NA)`
+#' * `Missing (Blank)`
 #'
 #' @examples
 #' chi_check("0101011237")
 #' chi_check(c("0101201234", "3201201234"))
 #'
 #' library(dplyr)
-#' df <- tibble(chi = c("3213201234", "123456789", "12345678900", "010120123?", NA))
+#' df <- tibble(chi = c(
+#'   "3213201234",
+#'   "123456789",
+#'   "12345678900",
+#'   "010120123?",
+#'   NA
+#' ))
 #' df %>%
 #'   mutate(validity = chi_check(chi))
 #' @export

R/chi_pad.R

@@ -1,7 +1,7 @@
 #' @title Add a leading zero to nine-digit CHI numbers
 #'
-#' @description \code{chi_pad} takes a nine-digit CHI number with
-#' \code{character} class and prefixes it with a zero. Any values provided
+#' @description `chi_pad` takes a nine-digit CHI number with
+#' `character` class and prefixes it with a zero. Any values provided
 #' which are not a string comprised of nine numeric digits remain unchanged.
 #'
 #' @details The Community Health Index (CHI) is a register of all patients in
@@ -14,21 +14,24 @@
 #' zero.
 #'
 #' While a CHI number is made up exclusively of numeric digits, it cannot be
-#' stored with \code{numeric} class in R. This is because leading zeros in
+#' stored with `numeric` class in R. This is because leading zeros in
 #' numeric values are silently dropped, a practice not exclusive to R. For this
-#' reason, \code{chi_pad} accepts input values of \code{character} class
+#' reason, `chi_pad` accepts input values of `character` class
 #' only, and returns values of the same class. It does not assess the validity
-#' of a CHI number - please see \code{\link{chi_check}} for that.
+#' of a CHI number - please see [chi_check()] for that.
 #'
 #' @inheritParams chi_check
 #'
+#' @return The original character vector with CHI numbers padded if applicable.
+#'
 #' @examples
 #' chi_pad(c("101011237", "101201234"))
 #' @export
-
 chi_pad <- function(x) {
   if (!inherits(x, "character")) {
-    cli::cli_abort("The input must be a {.cls character} vector, not a {.cls {class(x)}} vector.")
+    cli::cli_abort(
+      "The input must be a {.cls character} vector, not a {.cls {class(x)}} vector."
+    )
   }
 
   # Add a leading zero to any string comprised of nine numeric digits

R/create_age_groups.R

@@ -1,31 +1,31 @@
 #' Create age groups
 #'
 #' @description
-#' \code{create_age_groups()} takes a numeric vector and assigns each age to the
+#' `create_age_groups()` takes a numeric vector and assigns each age to the
 #' appropriate age group.
 #'
 #' @param x a vector of numeric values
-#' @param from the start of the smallest age group. The default is \code{0}.
-#' @param to the end point of the age groups. The default is \code{90}.
-#' @param by the size of the age groups. The default is \code{5}.
+#' @param from the start of the smallest age group. The default is `0`.
+#' @param to the end point of the age groups. The default is `90`.
+#' @param by the size of the age groups. The default is `5`.
 #' @param as_factor The default behaviour is to return a character vector. Use
-#' \code{TRUE} to return a factor vector instead.
+#' `TRUE` to return a factor vector instead.
 #'
 #' @return A character vector, where each element is the age group for the
-#' corresponding element in \code{x}. If \code{as_factor = TRUE}, a factor
+#' corresponding element in `x`. If `as_factor = TRUE`, a factor
 #' vector is returned instead.
 #'
 #' @details
-#' The \code{from}, \code{to} and \code{by} values are used to create distinct
-#' age groups. \code{from} dictates the starting age of the lowest age group,
-#' and \code{by} indicates how wide each group should be. \code{to} stipulates
+#' The `from`, `to` and `by` values are used to create distinct
+#' age groups. `from` dictates the starting age of the lowest age group,
+#' and `by` indicates how wide each group should be. `to` stipulates
 #' the cut-off point at which all ages equal to or greater than this value
-#' should be categorised together in a \code{to+} group. If the specified value
-#' of \code{to} is not a multiple of \code{by}, the value of \code{to} is
-#' rounded down to the nearest multiple of \code{by}.
+#' should be categorised together in a `to+` group. If the specified value
+#' of `to` is not a multiple of `by`, the value of `to` is
+#' rounded down to the nearest multiple of `by`.
 #'
-#' The default values of \code{from}, \code{to} and \code{by} correspond to the
-#' \href{https://www.opendata.nhs.scot/dataset/standard-populations/resource/edee9731-daf7-4e0d-b525-e4c1469b8f69}{European Standard Population}
+#' The default values of `from`, `to` and `by` correspond to the
+#' [European Standard Population](https://www.opendata.nhs.scot/dataset/standard-populations/resource/edee9731-daf7-4e0d-b525-e4c1469b8f69)
 #' age groups.
 #'
 #' @examples

R/data.R

@@ -1,22 +1,22 @@
 #' Codes and names of Scottish geographical and administrative areas.
 #'
 #' A dataset containing Scotland's geography codes and associated area names.
-#' It is used within \code{\link{match_area}}.
+#' It is used within [match_area()].
 #'
-#' @details \code{geo_code} contains geography codes pertaining to Health
+#' @details `geo_code` contains geography codes pertaining to Health
 #' Boards, Council Areas, Health and Social Care Partnerships, Intermediate
 #' Zones, Data Zones (2001 and 2011), Electoral Wards, Scottish Parliamentary
 #' Constituencies, UK Parliamentary Constituencies, Travel to work areas,
 #' National Parks, Community Health Partnerships, Localities (S19),
 #' Settlements (S20) and Scotland.
 #'
-#' @seealso The script used to create the \code{area_lookup} dataset on
-#' \href{https://github.com/Public-Health-Scotland/phsmethods/blob/master/data-raw/area_lookup.R}{GitHub}.
+#' @seealso The script used to create the `area_lookup` dataset on
+#' [GitHub](https://github.com/Public-Health-Scotland/phsmethods/blob/master/data-raw/area_lookup.R).
 #'
-#' @format A \code{\link[tibble]{tibble}} with 2 variables and over 17,000 rows:
+#' @format A [tibble::tibble()] with 2 variables and over 17,000 rows:
 #' \describe{
 #'   \item{geo_code}{Standard geography code - 9 characters}
 #'   \item{area_name}{Name of the area the code represents}
 #' }
-#' @source \url{https://statistics.gov.scot/}
+#' @source <https://statistics.gov.scot/>
 "area_lookup"