From cbce2333d4e560f82c2f20a65d0d649cce3e46ea Mon Sep 17 00:00:00 2001 From: Florian Mayer Date: Sun, 31 Mar 2024 18:01:14 +0800 Subject: [PATCH] Update contrib guide on functions --- CONTRIBUTING.md | 30 +++++++++++++++++++++++ R/entity_detail.R | 21 +++------------- man-roxygen/tpl-auth-missing.R | 3 +++ man-roxygen/tpl-compat-2022-3.R | 4 +++ man-roxygen/tpl-names-cleaned-top-level.R | 4 +++ man-roxygen/tpl-rusetup.R | 2 +- man-roxygen/tpl-structure-nested.R | 8 ++++++ man/entity_detail.Rd | 25 ------------------- 8 files changed, 54 insertions(+), 43 deletions(-) create mode 100644 man-roxygen/tpl-auth-missing.R create mode 100644 man-roxygen/tpl-compat-2022-3.R create mode 100644 man-roxygen/tpl-names-cleaned-top-level.R create mode 100644 man-roxygen/tpl-structure-nested.R diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5a28b936..68ba7ae8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -67,6 +67,36 @@ revealing sensitive information. Never include credentials in your reprex. Some changes have intricate internal and external dependencies, which are easy to miss and break. These checklists aim to avoid these pitfalls. +#### Adding a function +Discuss and agree on function naming with the `pyODK` developers. + +In the function documentation, include the following components: + +* Title +* Lifecycle badge +* Documentation from the official ODK Central API docs +* Additional paragraphs (see e.g. `entity_detail.R`): Factor out commonly used + text fragments into `man-roxygen` fragments. +* Link the relevant ODK Central API docs and surround the link with `# nolint start / end` mufflers for linter warnings about the line length. +* Link to the correct reference family topic. If adding a new topic, + update `pkgdown.yml`. +* List all parameters and export the function as usual. +* Add examples showing basic usage inside a `\dontrun{}` block. Examples have + no access to the test server and will only work for internal helpers which + do not access the ODK Central API. + +Inside the function: + +* Gatecheck for missing parameters via `yell_if_missing`. +* Gatecheck for the minimum ODK Central version. +* Prepare lengthy components of the `httr` call if it improves legibility. +* Use the native R pipe where possible. `ruODK` still re-exports the magrittr pipe. +* Parse response content as `utf-8`. +* Clean column names with `janitor::clean_names()`. + +Link to tests: +* Add a commented out `# usethis::use_test("entity_detail") # nolint` to functions and a commented out `# usethis::use_r("entity_detail") # nolint` to tests. This serves both to create the correct files and as a convenient shortcut between both. + #### Adding a dependency * Update DESCRIPTION * Update GH Actions install workflows - do R package deps have system deps? diff --git a/R/entity_detail.R b/R/entity_detail.R index dcdee40f..def4eb3c 100644 --- a/R/entity_detail.R +++ b/R/entity_detail.R @@ -30,23 +30,10 @@ #' After that, the conflict field will be null until a new conflicting version #' is received. #' -#' ## Structure -#' The response from ODK Central from this endpoint is irregular and dynamic. -#' `ruODK` preserves the original structure as not to introduce additional -#' complexity. If a use case exists to decompose the original structure further -#' please create a GitHub issue. -#' -#' ## Names -#' Names are cleaned at the top level only. List columns contain original -#' `camelCase` names. -#' -#' ## Authentication -#' `entity_detail()` will fail with incorrect or missing authentication. -#' -#' ## Compatibility -#' 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-auth-missing +#' @template tpl-compat-2022-3 #' @template param-pid #' @template param-did #' @template param-eid diff --git a/man-roxygen/tpl-auth-missing.R b/man-roxygen/tpl-auth-missing.R new file mode 100644 index 00000000..3576f265 --- /dev/null +++ b/man-roxygen/tpl-auth-missing.R @@ -0,0 +1,3 @@ +#' ## Authentication +#' This function will fail with incorrect or missing authentication. +#' diff --git a/man-roxygen/tpl-compat-2022-3.R b/man-roxygen/tpl-compat-2022-3.R new file mode 100644 index 00000000..d15d1874 --- /dev/null +++ b/man-roxygen/tpl-compat-2022-3.R @@ -0,0 +1,4 @@ +#' ## Compatibility +#' This function is supported from ODK Central v2022.3 and will warn if the +#' given `odkc_version` is lower. +#' diff --git a/man-roxygen/tpl-names-cleaned-top-level.R b/man-roxygen/tpl-names-cleaned-top-level.R new file mode 100644 index 00000000..41f74cb8 --- /dev/null +++ b/man-roxygen/tpl-names-cleaned-top-level.R @@ -0,0 +1,4 @@ +#' ## Names +#' Names are cleaned at the top level only. List columns contain original +#' `camelCase` names. +#' diff --git a/man-roxygen/tpl-rusetup.R b/man-roxygen/tpl-rusetup.R index 3700d9d1..512ccfdb 100644 --- a/man-roxygen/tpl-rusetup.R +++ b/man-roxygen/tpl-rusetup.R @@ -1,2 +1,2 @@ #' # See vignette("setup") for setup and authentication options -#' # ruODK::ru_setup(svc = "....svc", un = "me@email.com", pw = "...") +#' # ruODK::ru_setup(svc = "... .svc", un = "...", pw = "...") diff --git a/man-roxygen/tpl-structure-nested.R b/man-roxygen/tpl-structure-nested.R new file mode 100644 index 00000000..7378a0b7 --- /dev/null +++ b/man-roxygen/tpl-structure-nested.R @@ -0,0 +1,8 @@ +#' ## Structure +#' The response from ODK Central from this endpoint is irregular and dynamic. +#' Depending on the life history of records in ODK Central, some parts may be +#' populated with deeply nested structures, empty, or missing. +#' `ruODK` preserves the original structure as not to introduce additional +#' complexity. If a use case exists to decompose the original structure further +#' please create a GitHub issue. +#' diff --git a/man/entity_detail.Rd b/man/entity_detail.Rd index 4b5fc9b5..6d5f5548 100644 --- a/man/entity_detail.Rd +++ b/man/entity_detail.Rd @@ -115,31 +115,6 @@ If an Entity has a conflict, it can be marked as resolved. After that, the conflict field will be null until a new conflicting version is received. } - -\subsection{Structure}{ - -The response from ODK Central from this endpoint is irregular and dynamic. -\code{ruODK} preserves the original structure as not to introduce additional -complexity. If a use case exists to decompose the original structure further -please create a GitHub issue. -} - -\subsection{Names}{ - -Names are cleaned at the top level only. List columns contain original -\code{camelCase} names. -} - -\subsection{Authentication}{ - -\code{entity_detail()} will fail with incorrect or missing authentication. -} - -\subsection{Compatibility}{ - -This function is supported from ODK Central v2022.3 and will warn if the -given \code{odkc_version} is lower. -} } \examples{ \dontrun{