Update contrib guide on functions

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? 

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

man-roxygen/tpl-auth-missing.R

@@ -0,0 +1,3 @@
+#' ## Authentication
+#' This function will fail with incorrect or missing authentication.
+#'

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.
+#'

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.
+#'

man-roxygen/tpl-rusetup.R

@@ -1,2 +1,2 @@
 #' # See vignette("setup") for setup and authentication options
-#' # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")
+#' # ruODK::ru_setup(svc = "... .svc", un = "...", pw = "...")

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.
+#'