Closes #22 #181 #201 #292 #298 Variety of small-scale general documen…

…tation updates (#303)

* feat: #22 add documentation to friendly_type_of

* feat: #181 add the appropriate URL

* feat: #201 #292 add documentation about PR guidance and codeowners

* chore: update wordlist for codeowners

* chore: add NEWS

---------

Co-authored-by: Zelos Zhu <zdz2101@github.com>

NAMESPACE

@@ -43,6 +43,7 @@ export(expect_dfs_equal)
 export(expr_c)
 export(extract_vars)
 export(filter_if)
+export(friendly_type_of)
 export(get_constant_vars)
 export(get_dataset)
 export(get_duplicates)

NEWS.md

@@ -21,7 +21,9 @@
 - Guidance around issues and merging updated (#286)
 - Common R CMD troubleshooting made into separate vignette (#286)
 - Documentation of `get_dataset()` was improved. (#271)
-- Minor updates to programming strategy were added (#213, #240, #260)
+- Documentation of `friendly_type_of()` was provided (#22)
+- Minor updates to programming strategy were added (#181, #213, #240, #260)
+- Minor updates to pull request review guidance were added (#201, #292)
 
 ## Various
 

R/compat_friendly_type.R

@@ -1,10 +1,21 @@
-#' Return English-friendly Type
+#' Return English-friendly messaging for object-types
+#'
 #' @param x Any R object.
 #' @param value Whether to describe the value of `x`.
 #' @param length Whether to mention the length of vectors and lists.
+#'
+#' @details This helper function aids us in forming user-friendly messages that gets
+#' called through `what_is_it()`, which is often used in the assertion functions
+#' to identify what object-type the user passed through an argument instead of
+#' an expected-type.
+#'
+#' @export
+#'
 #' @return A string describing the type. Starts with an indefinite
 #'   article, e.g. "an integer vector".
-#' @noRd
+#'
+#' @keywords dev_utility
+#' @family dev_utility
 friendly_type_of <- function(x, value = TRUE, length = FALSE) { # nolint
   if (rlang::is_missing(x)) {
     return("absent")
@@ -70,6 +81,7 @@ friendly_type_of <- function(x, value = TRUE, length = FALSE) { # nolint
   type
 }
 
+# Used in building `friendly_type_of()` above
 .rlang_as_friendly_vector_type <- function(type, n_dim) {
   if (type == "list") {
     if (n_dim < 2) {
@@ -102,6 +114,7 @@ friendly_type_of <- function(x, value = TRUE, length = FALSE) { # nolint
   sprintf(type, kind)
 }
 
+# Used in building `friendly_type_of()` above
 .rlang_as_friendly_type <- function(type) {
   switch(type,
     list = "a list",
@@ -128,6 +141,7 @@ friendly_type_of <- function(x, value = TRUE, length = FALSE) { # nolint
   )
 }
 
+# Used in building `friendly_type_of()` above
 .rlang_stop_unexpected_typeof <- function(x, call = rlang::caller_env()) {
   rlang::abort(
     sprintf("Unexpected type <%s>.", typeof(x)),

inst/WORDLIST

@@ -1,5 +1,6 @@
 ADSL
 ADT
+ADVS
 ADaM
 ADaMs
 AEs
@@ -11,6 +12,7 @@ CDISC
 CMD
 Changelog
 Codebase
+Codeowners
 Cyclomatic
 DTC
 Datetime
@@ -42,7 +44,9 @@ adex
 adlb
 admiralci
 advs
+cmd
 codebase
+codeowner
 cyclomatic
 datatable
 datetime
@@ -57,10 +61,9 @@ flexibilities
 functions’
 funder
 github
-hotfixes
 hotfix
+hotfixes
 insightsengineering
-lifecycle
 linter
 lintr
 lockfile
@@ -69,7 +72,6 @@ optionality
 pkgs
 pre
 proc
-quosure
 quosures
 repo
 reproducibility
@@ -85,4 +87,3 @@ useR
 validatoR
 xxxx
 yyyyy
-cmd

vignettes/pr_review_guidance.Rmd

@@ -53,6 +53,12 @@ For a pull request to be merged into `devel` it needs to pass the automated CI c
 
 -   all files affected by the implemented changes, e.g. vignettes and templates, are updated
 
+## Codeowners and PR Guidance
+
+As the creator of a PR, the assignment of a reviewer can be unclear. For most PRs, feel free to select a few members of the core development team. These individuals scan each repository on a regular basis as well and may provide his/her review even if not originally included as a selected reviewer. 
+
+Sometimes, the development of a function or a vignette falls under a specific-topic, e.g. labs or PK/PD. Please ensure you include an appropriate reviewer if you are modifying files that rely on domain-expertise. We try to maintain an active list for domain-specific topics that will automatically tag an appropriate reviewer using our `CODEOWNERS` file, located in the `.github` folder. If you are interested in being a codeowner, reach out to the development team.
+
 # So much Red Tape!
 
 The `{admiral}` development team is aware and sympathetic to the great many checks, processes and documents needed to work through in order to do a compliant Pull Request. The `task-list-completed` GitHub workflow was created to help reduce this burden on contributors by providing a standardized checklist that compiles information from the Pull Request Review Guidance, [Programming Strategy](programming_strategy.html) and [Development Process](development_process.html) vignettes.

vignettes/programming_strategy.Rmd

@@ -146,7 +146,7 @@ documentation of `set_admiral_options()`.
 
 | Other Common Function Name Terms             | Description                                                                                         |
 |----------------------------------------------|-----------------------------------------------------------------------------------------------------|
-| `_merged_` / `_joined_` / `_extreme_`        | Functions that follow the generic function user-guide.                                              |
+| `_merged_` / `_joined_` / `_extreme_`        | Functions that follow the [generic function user-guide](https://pharmaverse.github.io/admiral/cran-release/articles/generic.html).                                              |