Clean up docs for entity management functions

* Refactor yell_if_missing to include did and eid
* Refactor shared docs into templates
* Add headings to docs

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: ruODK
 Title: An R Client for the ODK Central API
-Version: 1.4.9.9005
+Version: 1.4.9.9006
 Authors@R: 
     c(person(given = c("Florian", "W."),
              family = "Mayer",

R/entity_detail.R

@@ -1,4 +1,4 @@
-#' Show details of one Entity.
+#' Show metadata and current data of one Entity.
 #'
 #' `r lifecycle::badge("maturing")`
 #'
@@ -86,15 +86,7 @@ entity_detail <- function(pid = get_default_pid(),
                             "ymd"
                           ),
                           tz = get_default_tz()) {
-  yell_if_missing(url, un, pw, pid = pid)
-
-  if (is.null(did)) {
-    ru_msg_abort("entity_detail requires the Entity List name as 'did=\"name\"'.")
-  }
-
-  if (is.null(eid)) {
-    ru_msg_abort("entity_detail requires the Entity UUID as 'eid=\"uuid\"'.")
-  }
+  yell_if_missing(url, un, pw, pid = pid, did = did, eid = eid)
 
   if (odkc_version |> semver_lt("2022.3")) {
     ru_msg_warn("entity_detail is supported from v2022.3")
@@ -114,7 +106,6 @@ entity_detail <- function(pid = get_default_pid(),
     yell_if_error(url, un, pw) |>
     httr::content(encoding = "utf-8") |>
     # purrr::list_transpose() |>
-    #
     # tibble::enframe() |>
     # tibble::as_tibble(.name_repair = "universal") |>
     # tidyr::pivot_wider(names_from = "name", values_from = "value") |>

R/entity_list.R

@@ -14,7 +14,7 @@
 #' @template tpl-compat-2022-3
 #' @template param-pid
 #' @template param-did
-#' @param deleted (bool) Whether to get only deleted entities (`TRUE`) or not
+#' @param deleted (lgl) Whether to get only deleted entities (`TRUE`) or not
 #'   (`FALSE`). Default: `FALSE`.
 #' @template param-url
 #' @template param-auth
@@ -66,11 +66,7 @@ entity_list <- function(pid = get_default_pid(),
                           "ymd"
                         ),
                         tz = get_default_tz()) {
-  yell_if_missing(url, un, pw, pid = pid)
-
-  if (is.null(did)) {
-    ru_msg_abort("entity_list requires the Entity List name as 'did=\"name\"'.")
-  }
+  yell_if_missing(url, un, pw, pid = pid, did = did)
 
   if (odkc_version |> semver_lt("2022.3")) {
     ru_msg_warn("entity_list is supported from v2022.3")

R/entitylist_detail.R

@@ -2,14 +2,12 @@
 #'
 #' `r lifecycle::badge("maturing")`
 #'
-#' An Entity List is a named collection of Entities that have the same
-#' properties.
-#' Entity List can be linked to Forms as Attachments.
-#' This will make it available to clients as an automatically-updating CSV.
-#'
-#' This function is supported from ODK Central v2022.3 and will warn if the
-#' given odkc_version is lower.
-#'
+#' @template tpl-structure-nested
+#' @template tpl-names-cleaned-top-level
+#' @template tpl-def-entitylist
+#' @template tpl-entitylist-dataset
+#' @template tpl-auth-missing
+#' @template tpl-compat-2022-3
 #' @template param-pid
 #' @template param-did
 #' @template param-url
@@ -32,15 +30,19 @@
 #' # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")
 #'
 #' ds <- entitylist_list(pid = get_default_pid())
+#'
 #' ds1 <- entitylist_detail(pid = get_default_pid(), did = ds$name[1])
 #'
 #' ds1 |> listviewer::jsonedit()
-#' ds1$linkedForms |>
+#'
+#' ds1$linked_forms |>
 #'   purrr::list_transpose() |>
 #'   tibble::as_tibble()
-#' ds1$sourceForms |>
+#'
+#' ds1$source_forms |>
 #'   purrr::list_transpose() |>
 #'   tibble::as_tibble()
+#'
 #' ds1$properties |>
 #'   purrr::list_transpose() |>
 #'   tibble::as_tibble()
@@ -61,11 +63,7 @@ entitylist_detail <- function(pid = get_default_pid(),
                                 "ymd"
                               ),
                               tz = get_default_tz()) {
-  yell_if_missing(url, un, pw, pid = pid)
-
-  if (is.null(did)) {
-    ru_msg_abort("entitylist_detail requires the Entity List name as 'did=\"name\"'.")
-  }
+  yell_if_missing(url, un, pw, pid = pid, did = did)
 
   if (odkc_version |> semver_lt("2022.3")) {
     ru_msg_warn("entitylist_detail is supported from v2022.3")
@@ -86,7 +84,8 @@ entitylist_detail <- function(pid = get_default_pid(),
     times = retries
   ) |>
     yell_if_error(url, un, pw) |>
-    httr::content(encoding = "utf-8")
+    httr::content(encoding = "utf-8") |>
+    janitor::clean_names()
 }
 
 # usethis::use_test("entitylist_detail") # nolint

R/entitylist_download.R

@@ -2,33 +2,33 @@
 #'
 #' `r lifecycle::badge("maturing")`
 #'
+#' ## CSV file
 #' The downloaded CSV file is named after the entity list name.
 #' The download location defaults to the current workdir, but can be modified
 #' to a different folder path which will be created if it doesn't exist.
 #'
-#' An Entity List is a named collection of Entities that have the same
-#' properties.
-#' Entity List can be linked to Forms as Attachments.
-#' This will make it available to clients as an automatically-updating CSV.
-#'
 #' Entity Lists can be used as Attachments in other Forms, but they can also be
 #' downloaded directly as a CSV file.
+#'
 #' The CSV format closely matches the OData Dataset (Entity List) Service
 #' format, with columns for system properties such as `__id` (the Entity UUID),
-#' `__createdAt`, `__creatorName`, etc., the Entity Label label, and the
-#' Dataset (Entity List )/Entity Properties themselves.
+#' `__createdAt`, `__creatorName`, etc., the Entity Label, and the
+#' Dataset (Entity List) or Entity Properties themselves.
 #' If any Property for an given Entity is blank (e.g. it was not captured by
 #' that Form or was left blank), that field of the CSV is blank.
 #'
-#' The ODK Central `$filter` querystring parameter can be used to filter on
+#' ## Filter
+#' The ODK Central `$filter` query string parameter can be used to filter on
 #' system-level properties, similar to how filtering in the OData Dataset
 #' (Entity List) Service works.
-#' Of the [OData filter specs](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#_Toc31358948)
+#' Of the [OData filter specs
+#' ](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#_Toc31358948)
 #' ODK Central implements a [growing set of features
 #' ](https://docs.getodk.org/central-api-odata-endpoints/#data-document).
 #' `ruODK` provides the parameter `filter` (str) which, if set, will be passed
 #' on to the ODK Central endpoint as is.
 #'
+#' ## Resuming downloads through ETag
 #' The ODK Central endpoint supports the [`ETag` header
 #' ](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag), which can
 #' be used to avoid downloading the same content more than once.
@@ -44,6 +44,10 @@
 #' a previous call to `entitylist_download()`. `ruODK` strips the `W/\"` and
 #' `\"` from the returned etag and expects the stripped etag as parameter.
 #'
+#' @template tpl-def-entitylist
+#' @template tpl-entitylist-dataset
+#' @template tpl-auth-missing
+#' @template tpl-compat-2022-3
 #' @template param-pid
 #' @template param-did
 #' @template param-url
@@ -56,11 +60,11 @@
 #'   which is the format of the etag returned by `entitylist_download()`.
 #'   If provided, only new entities will be returned.
 #'   If the same `local_dir` is chosen and `overwrite` is set to `TRUE`,
-#'   the downloaded CSV will also be overwritte, losing the Entities downloaded
-#'   earlier.
-#'   Default: NULL (no filtering, all entities returned).
+#'   the downloaded CSV will also be overwritten, losing the previously
+#'   downloaded Entities.
+#'   Default: NULL (no filtering, all Entities returned).
 #' @param filter (str) A valid filter string.
-#'   Default: NULL (no filtering, all entities returned).
+#'   Default: NULL (no filtering, all Entities returned).
 #' @param overwrite Whether to overwrite previously downloaded file,
 #'                 default: FALSE
 #' @template param-retries
@@ -74,7 +78,7 @@
 #'     200 if OK, 304 if a given etag finds no new entities created.
 #'   - etag (str) The ETag to use in subsequent calls to `entitylist_download()`
 #'   - downloaded_to (fs_path) The path to the downloaded CSV file
-#'   - downloaded_on (POSIXct) The time of download in the local timezome
+#'   - downloaded_on (POSIXct) The time of download in the local timezone
 # nolint start
 #' @seealso \url{https://docs.getodk.org/central-api-dataset-management/#datasets}
 # nolint end
@@ -86,6 +90,7 @@
 #' # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")
 #'
 #' ds <- entitylist_list(pid = get_default_pid())
+#'
 #' ds1 <- entitylist_download(pid = get_default_pid(), did = ds$name[1])
 #' # ds1$entities
 #' # ds1$etag
@@ -128,13 +133,7 @@ entitylist_download <- function(pid = get_default_pid(),
                                 tz = get_default_tz(),
                                 verbose = get_ru_verbose()) {
   # Gatecheck params
-  yell_if_missing(url, un, pw, pid = pid)
-
-  if (is.null(did)) {
-    ru_msg_abort(
-      "entitylist_download requires the Entity List name as 'did=\"name\"'."
-    )
-  }
+  yell_if_missing(url, un, pw, pid = pid, did = did)
 
   # Gatecheck ODKC version
   if (odkc_version |> semver_lt("2022.3")) {

R/entitylist_list.R

@@ -2,21 +2,13 @@
 #'
 #' `r lifecycle::badge("maturing")`
 #'
-#' While the API endpoint will return all Entity Lists for one Project,
-#' \code{\link{entitylist_list}} will fail with incorrect or missing
-#' authentication.
-#'
-#' An Entity List is a named collection of Entities that have the same properties.
-#' An Entity List can be linked to Forms as Attachments.
-#' This will make it available to clients as an automatically-updating CSV.
-#'
-#' ODK Central calls Entity Lists internally Datasets. `ruODK` chooses the term
-#' Entity Lists as it is used in the ODK Central user interface and conveys
-#' its relation to Entities better than the term Dataset.
-#'
-#' This function is supported from ODK Central v2022.3 and will warn if the
-#' given odkc_version is lower.
+#' The returned list is useful to retrieve the valid name of an Entity List for
+#' further use by functions of the Entity Management family.
 #'
+#' @template tpl-def-entitylist
+#' @template tpl-entitylist-dataset
+#' @template tpl-auth-missing
+#' @template tpl-compat-2022-3
 #' @template param-pid
 #' @template param-url
 #' @template param-auth

R/entitylist_update.R

@@ -3,31 +3,25 @@
 #' `r lifecycle::badge("maturing")`
 #'
 #' You can only update `approvalRequired` using this endpoint.
-#' The  approvalRequired flag controls the Entity creation flow;
+#' The  `approvalRequired` flag controls the Entity creation flow;
 #' if it is true then the Submission must be approved before an Entity can be
 #' created from it and if it is false then an Entity is created as soon as the
 #' Submission is received by the ODK Central.
 #' By default `approvalRequired` is false for the Entity Lists created after
-#' v2023.3. Entity Lists created prior to that will have approvalRequired set to
-#' true.
-#'
-#' An Entity List is a named collection of Entities that have the same
-#' properties.
-#' An Entity List can be linked to Forms as Attachments.
-#' This will make it available to clients as an automatically-updating CSV.
-#'
-#' This function is supported from ODK Central v2022.3 and will warn if the
-#' given odkc_version is lower.
-#'
-#' `r lifecycle::badge("maturing")`
+#' v2023.3. Entity Lists created prior to that will have `approvalRequired` set
+#' to true.
 #'
+#' @template tpl-def-entitylist
+#' @template tpl-entitylist-dataset
+#' @template tpl-auth-missing
+#' @template tpl-compat-2022-3
 #' @template param-pid
 #' @template param-did
-#' @param approval_required (lgl) The value to set approvalRequired to.
-#'   If TRUE, a submission must be approved before an entity is created,
-#'   if FALSE, an entity is created as soon as the submission is received by
+#' @param approval_required (lgl) The value to set `approvalRequired` to.
+#'   If TRUE, a Submission must be approved before an Entity is created,
+#'   if FALSE, an Entity is created as soon as the Submission is received by
 #'   ODK Central.
-#'   Default: FALSE.
+#'   Default: `FALSE`.
 #' @template param-url
 #' @template param-auth
 #' @template param-retries
@@ -80,11 +74,7 @@ entitylist_update <- function(pid = get_default_pid(),
                                 "ymd"
                               ),
                               tz = get_default_tz()) {
-  yell_if_missing(url, un, pw, pid = pid)
-
-  if (is.null(did)) {
-    ru_msg_abort("entitylist_update requires the Entity List name as 'did=\"name\"'.")
-  }
+  yell_if_missing(url, un, pw, pid = pid, did = did)
 
   if (odkc_version |> semver_lt("2022.3")) {
     ru_msg_warn("entitylist_update is supported from v2022.3")

R/isodt_to_local.R

@@ -13,7 +13,7 @@
 #'   `lubridate`.
 #'   Default: \code{c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz")}.
 #' @template param-tz
-#' @param quiet (bool) Used in `lubridate::parse_date_time(quiet=quiet)` to
+#' @param quiet (lgl) Used in `lubridate::parse_date_time(quiet=quiet)` to
 #'   suppress warnings from attempting to parse all empty values or columns.
 #'   Run with `quiet=FALSE` to show any `lubridate` warnings.
 #' @return A `lubridate` PosixCT datetime in the given timezone.

R/ru_setup.R

@@ -710,7 +710,9 @@ get_retries <- function() {
 #' testthat::expect_error(yell_if_missing("", "", "", ""))
 #' testthat::expect_error(yell_if_missing("", "", "", "", ""))
 #' testthat::expect_error(yell_if_missing("", "", "", "", "", ""))
-yell_if_missing <- function(url, un, pw, pid = NULL, fid = NULL, iid = NULL) {
+#' testthat::expect_error(yell_if_missing("", "", "", "", "", "", ""))
+#' testthat::expect_error(yell_if_missing("", "", "", "", "", "", "", ""))
+yell_if_missing <- function(url, un, pw, pid = NULL, fid = NULL, iid = NULL, did = NULL, eid = NULL) {
   if (is.null(url) || identical(url, "")) {
     ru_msg_abort("Missing ODK Central URL. ru_setup()?")
   }
@@ -729,6 +731,12 @@ yell_if_missing <- function(url, un, pw, pid = NULL, fid = NULL, iid = NULL) {
   if (!is.null(iid) && identical(iid, "")) {
     ru_msg_abort("Missing ODK Central submission instance ID.")
   }
+  if (!is.null(did) && identical(did, "")) {
+    ru_msg_abort("Missing ODK Central Entity List (dataset) name.")
+  }
+  if (!is.null(eid) && identical(eid, "")) {
+    ru_msg_abort("Missing ODK Central Entity UUID.")
+  }
 }
 
 #' Warn about failed web requests and give helpful troubleshooting tips.

man-roxygen/tpl-def-entitylist.R

@@ -0,0 +1,4 @@
+#' An Entity List is a named collection of Entities that have the same properties.
+#' An Entity List can be linked to Forms as Attachments.
+#' This will make it available to clients as an automatically-updating CSV.
+#'

man-roxygen/tpl-entitylist-dataset.R

@@ -0,0 +1,5 @@
+#' ## Entity Lists are Datasets
+#' ODK Central calls Entity Lists internally Datasets. `ruODK` chooses the term
+#' Entity Lists as it is used in the ODK Central user interface and conveys
+#' its relation to Entities better than the term Dataset.
+#'