improve documentation for redcap_delete()

ref #372

R/redcap-delete.R

@@ -33,12 +33,15 @@
 #' REDCap requires that at least one `record_id` value be passed to
 #' the delete call.
 #'
-#' When the project has arms, REDCapR has stricter requirement than REDCap.
+#' When the project has arms, REDCapR has stricter requirements than REDCap.
 #' If the REDCap project has arms, a value must be passed to
 #' `arm_of_records_to_delete`.  This is a different behavior than calling
-#' the server through cURL --which if the project has arms and no
-#' arm number is specified, then all arms are cleared of the
-#' specified `record_id`s.
+#' the server through cURL --which if no  arm number is specified,
+#' then all arms are cleared of the specified `record_id`s.
+#'
+#' Note that all longitudinal projects technically have arms, even if
+#' only one arm is defined.  Therefore a value of `arm_number` must be
+#' specified for all longitudinal projects.
 #'
 #' @author Jonathan Mang, Will Beasley
 #'
@@ -51,15 +54,23 @@
 #'
 #' @examples
 #' \dontrun{
-#' #Define some constants
-#' uri            <- "https://bbmc.ouhsc.edu/redcap/api/"
-#' token          <- "D70F9ACD1EDD6F151C6EA78683944E98"
+#' records_to_delete <- c(102, 103, 105, 120)
 #'
-#' # Read the dataset for the first time.
-#' result_read1   <- REDCapR::redcap_delete(redcap_uri=uri, token=token)
-#' ds1            <- result_read1$data
-#' ds1$telephone
+#' # Deleting from a non-longitudinal project with no defined arms:
+#' REDCapR::redcap_delete(
+#'   redcap_uri               = uri,
+#'   token                    = token,
+#'   records_to_delete        = records_to_delete,
+#' )
 #'
+#' # Deleting from a project that has arms or is longitudinal:
+#' arm_number <- 2L # Not the arm name
+#' REDCapR::redcap_delete(
+#'   redcap_uri               = uri,
+#'   token                    = token,
+#'   records_to_delete        = records_to_delete,
+#'   arm_of_records_to_delete = arm_number
+#' )
 #' }
 
 #' @export