format documentation

ref #425

R/REDCapR-package.R

@@ -1,12 +1,12 @@
 #' @docType package
 #' @name REDCapR-package
-#' @aliases REDCapR
+#' @aliases
+#' REDCapR
 #'
 #' @title R utilities for interacting with a REDCap data system
 #' <https://www.project-redcap.org/>
 #'
 #' @description
-#'
 #' Comprehensive documentation is also available at
 #' https://ouhscbbmc.github.io/REDCapR/.
 #'
@@ -39,7 +39,8 @@
 #' 2013-2017.
 #'
 #'
-#' @note The release version is available through
+#' @note
+#' The release version is available through
 #' [CRAN](https://cran.r-project.org/package=REDCapR) by running
 #' `install.packages('REDCapR')`.  The most recent development version is
 #' available through [GitHub](https://github.com/OuhscBbmc/REDCapR) by

R/constant.R

@@ -1,14 +1,20 @@
 #' @name constant
-#' @aliases constant constant_to_form_completion constant_to_form_rights
+#'
+#' @aliases
+#' constant constant_to_form_completion constant_to_form_rights
 #' constant_to_export_rights constant_to_access
-#' @title Collection of REDCap-specific constants
 #'
-#' @description Collection of constants defined by the REDCap developers.
+#' @title
+#' Collection of REDCap-specific constants
+#'
+#' @description
+#' Collection of constants defined by the REDCap developers.
 #'
 #' @param name Name of constant.  Required character.
 #'
-#' @return The constant's value.  Currently all are single integers,
-#'   but that could be expanded in the future.
+#' @return
+#' The constant's value.  Currently all are single integers,
+#' but that could be expanded in the future.
 #'
 #' @details
 #` Constants have the following groupings.
@@ -50,7 +56,8 @@
 #' [Editing files in another user's repository](https://docs.github.com/articles/editing-files-in-another-user-s-repository/) # nolint
 #' in the GitHub documentation.
 #'
-#' @author Will Beasley
+#' @author
+#' Will Beasley
 #'
 #' @examples
 #' REDCapR::constant("form_incomplete")  # Returns 0L

R/create-batch-glossary.R

@@ -1,7 +1,9 @@
-#' @title Creates a dataset that help batching long-running
+#' @title
+#' Creates a dataset that help batching long-running
 #' read and writes
 #'
-#' @description The function returns a [base::data.frame()] that other
+#' @description
+#' The function returns a [base::data.frame()] that other
 #' functions use to separate long-running read and write REDCap calls into
 #' multiple, smaller REDCap calls.  The goal is to (1) reduce the chance of
 #' time-outs, and (2) introduce little breaks between batches so that the
@@ -11,7 +13,8 @@
 #' @param batch_size The maximum number of subject records a single batch
 #' should contain.
 
-#' @return Currently, a [base::data.frame()] is returned with the following
+#' @return
+#' Currently, a [base::data.frame()] is returned with the following
 #' columns,
 #' * `id`: an `integer` that uniquely identifies the batch, starting at `1`.
 #' * `start_index`: the index of the first row in the batch. `integer`.
@@ -29,7 +32,8 @@
 #' [base::data.frame()] to disk as smaller files (such as a .csv).  The
 #' padded columns allow the OS to sort the batches/files in sequential order.
 #'
-#' @author Will Beasley
+#' @author
+#' Will Beasley
 #'
 #' @seealso
 #' See [redcap_read()] for a function that uses `create_batch_glossary`.

R/helpers-testing.R

@@ -1,7 +1,7 @@
 retrieve_credential_testing <- function(project_id = 153L, username = NA_character_) {
   checkmate::assert_integer(project_id, lower = 1, len = 1, any.missing = FALSE)
    REDCapR::retrieve_credential_local(
-    path_credential = system.file("misc/example.credentials", package="REDCapR"),
+    path_credential = system.file("misc/example.credentials", package = "REDCapR"),
     project_id      = project_id,
     username        = username
   )

R/kernel-api.R

@@ -1,7 +1,8 @@
-#' @title REDCapR internal function for calling the REDCap API
+#' @title
+#' REDCapR internal function for calling the REDCap API
 #'
-#' @description This function is used by other functions to read and write
-#' values.
+#' @description
+#' This function is used by other functions to read and write values.
 #'
 #' @param redcap_uri The
 #' [uri](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier)/url
@@ -16,9 +17,11 @@
 #' @param content_type The MIME value passed to [httr::content()].  Defaults
 #' to 'text/csv'.
 #'
-#' @return A [utils::packageVersion].
+#' @return
+#' A [utils::packageVersion].
 #'
-#' @details If the API call is unsuccessful, a value of
+#' @details
+#' If the API call is unsuccessful, a value of
 #' `base::package_version("0.0.0")` will be returned.  This ensures that a
 #' the function will always return an object of class [base::package_version].
 #' It guarantees the value can always be used in [utils::compareVersion()].
@@ -68,7 +71,6 @@ kernel_api <- function(
 
   status_code           <- result$status
   success               <- (status_code == 200L)
-  # raw_text              <- as.character(httr::content(result, as = "text"))
   raw_text              <- httr::content(
     x           = result,
     as          = "text",

R/metadata-utilities.R

@@ -1,19 +1,24 @@
 #' @name metadata_utilities
-#' @aliases regex_named_captures checkbox_choices
 #'
-#' @title Manipulate and interpret the metadata of a REDCap project
+#' @aliases
+#' regex_named_captures checkbox_choices
 #'
-#' @description A collection of functions that assists handling REDCap
+#' @title
+#' Manipulate and interpret the metadata of a REDCap project
+#'
+#' @description
+#' A collection of functions that assists handling REDCap
 #' project metadata.
 #'
 #' @param pattern The regular expression pattern.  Required.
 #' @param text The text to apply the regex against.  Required.
 #' @param select_choices The text containing the choices that should be parsed
-#'   to determine the `id` and `label` values.  Required.
+#' to determine the `id` and `label` values.  Required.
 #' @param perl Indicates if perl-compatible regexps should be used.
-#'   Default is `TRUE`. Optional.
+#' Default is `TRUE`. Optional.
 #'
-#' @return Currently, a [tibble::tibble()] is returned a row for each match,
+#' @return
+#' Currently, a [tibble::tibble()] is returned a row for each match,
 #' and a column for each *named* group within a match.  For the
 #' `retrieve_checkbox_choices()` function, the columns will be.
 #' * `id`: The numeric value assigned to each choice (in the data dictionary).
@@ -33,8 +38,11 @@
 #' since that the delimiter REDCap uses to separate choices
 #' presented to the user.
 #'
-#' @author Will Beasley
-#' @references See the official documentation for permissible characters in a
+#' @author
+#' Will Beasley
+#'
+#' @references
+#' See the official documentation for permissible characters in a
 #' checkbox label.
 #' *I'm bluffing here, because I don't know where this is located.
 #' If you know, please tell me.*
@@ -50,7 +58,8 @@
 #'   "3, Native Hawaiian or Other Pacific Islander | ",
 #'   "4, Black or African American | ",
 #'   "5, White | ",
-#'   "6, Unknown / Not Reported")
+#'   "6, Unknown / Not Reported"
+#' )
 #'
 #' # This calls the general function, and requires the correct regex pattern.
 #' REDCapR::regex_named_captures(pattern=pattern_boxes, text=choices_1)

R/project-dag-write.R

@@ -48,19 +48,19 @@ populate_project_dag_write <- function(batch = FALSE) {
   # testthat::expect_message(
     returned_object <- if (batch) {
       REDCapR::redcap_write(
-        ds          = ds_to_write,
-        redcap_uri  = project$redcap_uri,
-        token       = project$token,
-        verbose     = TRUE,
-        convert_logical_to_integer = TRUE
+        ds                          = ds_to_write,
+        redcap_uri                  = project$redcap_uri,
+        token                       = project$token,
+        verbose                     = TRUE,
+        convert_logical_to_integer  = TRUE
       )
     } else {
       REDCapR::redcap_write_oneshot(
-        ds          = ds_to_write,
-        redcap_uri  = project$redcap_uri,
-        token       = project$token,
-        verbose     = TRUE,
-        convert_logical_to_integer = TRUE
+        ds                          = ds_to_write,
+        redcap_uri                  = project$redcap_uri,
+        token                       = project$token,
+        verbose                     = TRUE,
+        convert_logical_to_integer  = TRUE
       )
     }
   # )
@@ -124,14 +124,14 @@ clean_start_dag_write <- function(batch = FALSE, delay_in_seconds = 1) {
     regexp = "clear_project_dag_write success: TRUE."
   )
   testthat::expect_true(clear_result, "Clearing the results from the dag_write project should be successful.")
-  base::Sys.sleep(delay_in_seconds) #Pause after deleting records.
+  base::Sys.sleep(delay_in_seconds) # Pause after deleting records.
 
   testthat::expect_message(
     populate_result <- populate_project_dag_write(batch = batch),
     regexp = "populate_project_dag_write success: TRUE."
   )
   testthat::expect_true(populate_result$is_success, "Population of the dag_write project should be successful.")
-  base::Sys.sleep(delay_in_seconds) #Pause after writing records.
+  base::Sys.sleep(delay_in_seconds) # Pause after writing records.
 
   populate_result
 }

R/project-delete-multiple-arm.R

@@ -95,14 +95,14 @@ clean_start_delete_multiple_arm <- function(delay_in_seconds = 1) {
     regexp = "clear_project_delete_multiple_arm success: TRUE."
   )
   testthat::expect_true(clear_result, "Clearing the results from the delete_multiple_arm project should be successful.")
-  base::Sys.sleep(delay_in_seconds) #Pause after deleting records.
+  base::Sys.sleep(delay_in_seconds) # Pause after deleting records.
 
   testthat::expect_message(
     populate_result <- populate_project_delete_multiple_arm(),
     regexp = "populate_project_delete_multiple_arm success: TRUE."
   )
   testthat::expect_true(populate_result$is_success, "Population of the delete_multiple_arm project should be successful.")
-  base::Sys.sleep(delay_in_seconds) #Pause after writing records.
+  base::Sys.sleep(delay_in_seconds) # Pause after writing records.
 
   populate_result
 }

R/project-delete-single-arm.R

@@ -95,14 +95,14 @@ clean_start_delete_single_arm <- function(delay_in_seconds = 1) {
     regexp = "clear_project_delete_single_arm success: TRUE."
   )
   testthat::expect_true(clear_result, "Clearing the results from the delete_single_arm project should be successful.")
-  base::Sys.sleep(delay_in_seconds) #Pause after deleting records.
+  base::Sys.sleep(delay_in_seconds) # Pause after deleting records.
 
   testthat::expect_message(
     populate_result <- populate_project_delete_single_arm(),
     regexp = "populate_project_delete_single_arm success: TRUE."
   )
   testthat::expect_true(populate_result$is_success, "Population of the delete_single_arm project should be successful.")
-  base::Sys.sleep(delay_in_seconds) #Pause after writing records.
+  base::Sys.sleep(delay_in_seconds) # Pause after writing records.
 
   populate_result
 }

R/project-simple.R

@@ -45,19 +45,19 @@ populate_project_simple <- function(batch = FALSE) {
   testthat::expect_message(
     returned_object <- if (batch) {
       REDCapR::redcap_write(
-        ds          = ds_to_write,
-        redcap_uri  = project$redcap_uri,
-        token       = project$token,
-        verbose     = TRUE,
-        convert_logical_to_integer = TRUE
+        ds                          = ds_to_write,
+        redcap_uri                  = project$redcap_uri,
+        token                       = project$token,
+        verbose                     = TRUE,
+        convert_logical_to_integer  = TRUE
       )
     } else {
       REDCapR::redcap_write_oneshot(
-        ds          = ds_to_write,
-        redcap_uri  = project$redcap_uri,
-        token       = project$token,
-        verbose     = TRUE,
-        convert_logical_to_integer = TRUE
+        ds                          = ds_to_write,
+        redcap_uri                  = project$redcap_uri,
+        token                       = project$token,
+        verbose                     = TRUE,
+        convert_logical_to_integer  = TRUE
       )
     }
   )

R/redcap-arm-export.R

@@ -1,6 +1,8 @@
-#' @title Export Arms
+#' @title
+#' Export Arms
 #'
-#' @description Export Arms of a REDCap project
+#' @description
+#' Export Arms of a REDCap project
 #'
 #' @param redcap_uri The
 #' [uri](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier)/url
@@ -9,15 +11,15 @@
 #' Required.
 #' @param token The user-specific string that serves as the password for a
 #' project.  Required.
-#'
 #' @param verbose A boolean value indicating if `message`s should be printed
 #' to the R console during the operation.  The verbose output might contain
 #' sensitive information (*e.g.* PHI), so turn this off if the output might
 #' be visible somewhere public. Optional.
 #' @param config_options A list of options passed to [httr::POST()].
 #' See details at [httr::httr_options()]. Optional.
 #'
-#' @return Currently, a list is returned with the following elements:
+#' @return
+#' Currently, a list is returned with the following elements:
 #' * `has_arms`: a `logical` value indicating if the REDCap project has
 #' arms (*i.e.*, "TRUE") or is a classic non-longitudinal project
 #' (*i.e.*, "FALSE").
@@ -35,9 +37,11 @@
 #' REDCap.  If an operation is successful, the `raw_text` is returned as an
 #' empty string to save RAM.
 #'
-#' @author Will Beasley
+#' @author
+#' Will Beasley
 #'
-#' @references The official documentation can be found on the 'API Help Page'
+#' @references
+#' The official documentation can be found on the 'API Help Page'
 #' and 'API Examples' pages on the REDCap wiki (*i.e.*,
 #' https://community.projectredcap.org/articles/456/api-documentation.html and
 #' https://community.projectredcap.org/articles/462/api-examples.html).

R/redcap-column-sanitize.R

@@ -1,6 +1,8 @@
-#' @title Sanitize to adhere to REDCap character encoding requirements
+#' @title
+#' Sanitize to adhere to REDCap character encoding requirements
 #'
-#' @description Replace non-ASCII characters with legal characters that won't
+#' @description
+#' Replace non-ASCII characters with legal characters that won't
 #' cause problems when writing to a REDCap project.
 #'
 #' @param d The [base::data.frame()] containing the dataset used to update
@@ -23,7 +25,8 @@
 #' `R 3.1.0`, the OSes use similar, but different, versions to convert the
 #' characters.  Be aware of this in case you notice OS-dependent differences.
 #'
-#' @author Will Beasley
+#' @author
+#' Will Beasley
 #'
 #' @examples
 #' # Typical examples are not shown because they require non-ASCII encoding,