diff --git a/NAMESPACE b/NAMESPACE index 06c743c3..a8eabf60 100644 --- a/NAMESPACE +++ b/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) diff --git a/NEWS.md b/NEWS.md index 53b93dfe..bfd323a2 100644 --- a/NEWS.md +++ b/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 diff --git a/R/compat_friendly_type.R b/R/compat_friendly_type.R index 5897a04b..01ef4ad4 100644 --- a/R/compat_friendly_type.R +++ b/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)), diff --git a/inst/WORDLIST b/inst/WORDLIST index d8d173b8..abee8117 100644 --- a/inst/WORDLIST +++ b/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 diff --git a/man/arg_name.Rd b/man/arg_name.Rd index 78fd3c79..5282bea0 100644 --- a/man/arg_name.Rd +++ b/man/arg_name.Rd @@ -23,6 +23,7 @@ Developer Utility Functions: \code{\link{convert_dtm_to_dtc}()}, \code{\link{extract_vars}()}, \code{\link{filter_if}()}, +\code{\link{friendly_type_of}()}, \code{\link{valid_time_units}()}, \code{\link{vars2chr}()} } diff --git a/man/contains_vars.Rd b/man/contains_vars.Rd index 411aac94..77c0f1e5 100644 --- a/man/contains_vars.Rd +++ b/man/contains_vars.Rd @@ -25,6 +25,7 @@ Developer Utility Functions: \code{\link{convert_dtm_to_dtc}()}, \code{\link{extract_vars}()}, \code{\link{filter_if}()}, +\code{\link{friendly_type_of}()}, \code{\link{valid_time_units}()}, \code{\link{vars2chr}()} } diff --git a/man/convert_dtm_to_dtc.Rd b/man/convert_dtm_to_dtc.Rd index 6ea86669..5940d4b1 100644 --- a/man/convert_dtm_to_dtc.Rd +++ b/man/convert_dtm_to_dtc.Rd @@ -25,6 +25,7 @@ Developer Utility Functions: \code{\link{contains_vars}()}, \code{\link{extract_vars}()}, \code{\link{filter_if}()}, +\code{\link{friendly_type_of}()}, \code{\link{valid_time_units}()}, \code{\link{vars2chr}()} } diff --git a/man/extract_vars.Rd b/man/extract_vars.Rd index 198ed3eb..6b2a8bff 100644 --- a/man/extract_vars.Rd +++ b/man/extract_vars.Rd @@ -31,6 +31,7 @@ Developer Utility Functions: \code{\link{contains_vars}()}, \code{\link{convert_dtm_to_dtc}()}, \code{\link{filter_if}()}, +\code{\link{friendly_type_of}()}, \code{\link{valid_time_units}()}, \code{\link{vars2chr}()} } diff --git a/man/filter_if.Rd b/man/filter_if.Rd index 23cd1447..e15cdf19 100644 --- a/man/filter_if.Rd +++ b/man/filter_if.Rd @@ -26,6 +26,7 @@ Developer Utility Functions: \code{\link{contains_vars}()}, \code{\link{convert_dtm_to_dtc}()}, \code{\link{extract_vars}()}, +\code{\link{friendly_type_of}()}, \code{\link{valid_time_units}()}, \code{\link{vars2chr}()} } diff --git a/man/friendly_type_of.Rd b/man/friendly_type_of.Rd new file mode 100644 index 00000000..c52ba7c5 --- /dev/null +++ b/man/friendly_type_of.Rd @@ -0,0 +1,42 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/compat_friendly_type.R +\name{friendly_type_of} +\alias{friendly_type_of} +\title{Return English-friendly messaging for object-types} +\usage{ +friendly_type_of(x, value = TRUE, length = FALSE) +} +\arguments{ +\item{x}{Any R object.} + +\item{value}{Whether to describe the value of \code{x}.} + +\item{length}{Whether to mention the length of vectors and lists.} +} +\value{ +A string describing the type. Starts with an indefinite +article, e.g. "an integer vector". +} +\description{ +Return English-friendly messaging for object-types +} +\details{ +This helper function aids us in forming user-friendly messages that gets +called through \code{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. +} +\seealso{ +Developer Utility Functions: +\code{\link{\%notin\%}()}, +\code{\link{\%or\%}()}, +\code{\link{arg_name}()}, +\code{\link{contains_vars}()}, +\code{\link{convert_dtm_to_dtc}()}, +\code{\link{extract_vars}()}, +\code{\link{filter_if}()}, +\code{\link{valid_time_units}()}, +\code{\link{vars2chr}()} +} +\concept{dev_utility} +\keyword{dev_utility} diff --git a/man/grapes-notin-grapes.Rd b/man/grapes-notin-grapes.Rd index 61c33f64..d65221dd 100644 --- a/man/grapes-notin-grapes.Rd +++ b/man/grapes-notin-grapes.Rd @@ -26,6 +26,7 @@ Developer Utility Functions: \code{\link{convert_dtm_to_dtc}()}, \code{\link{extract_vars}()}, \code{\link{filter_if}()}, +\code{\link{friendly_type_of}()}, \code{\link{valid_time_units}()}, \code{\link{vars2chr}()} } diff --git a/man/grapes-or-grapes.Rd b/man/grapes-or-grapes.Rd index b7c6da50..4c93ede5 100644 --- a/man/grapes-or-grapes.Rd +++ b/man/grapes-or-grapes.Rd @@ -30,6 +30,7 @@ Developer Utility Functions: \code{\link{convert_dtm_to_dtc}()}, \code{\link{extract_vars}()}, \code{\link{filter_if}()}, +\code{\link{friendly_type_of}()}, \code{\link{valid_time_units}()}, \code{\link{vars2chr}()} } diff --git a/man/valid_time_units.Rd b/man/valid_time_units.Rd index 44d3d8ea..ed0b27d9 100644 --- a/man/valid_time_units.Rd +++ b/man/valid_time_units.Rd @@ -21,6 +21,7 @@ Developer Utility Functions: \code{\link{convert_dtm_to_dtc}()}, \code{\link{extract_vars}()}, \code{\link{filter_if}()}, +\code{\link{friendly_type_of}()}, \code{\link{vars2chr}()} } \concept{dev_utility} diff --git a/man/vars2chr.Rd b/man/vars2chr.Rd index 039beb93..15d59450 100644 --- a/man/vars2chr.Rd +++ b/man/vars2chr.Rd @@ -32,6 +32,7 @@ Developer Utility Functions: \code{\link{convert_dtm_to_dtc}()}, \code{\link{extract_vars}()}, \code{\link{filter_if}()}, +\code{\link{friendly_type_of}()}, \code{\link{valid_time_units}()} } \concept{dev_utility} diff --git a/vignettes/pr_review_guidance.Rmd b/vignettes/pr_review_guidance.Rmd index d39484f2..248936a5 100644 --- a/vignettes/pr_review_guidance.Rmd +++ b/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. diff --git a/vignettes/programming_strategy.Rmd b/vignettes/programming_strategy.Rmd index 9ab2964a..775b3c5c 100644 --- a/vignettes/programming_strategy.Rmd +++ b/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). |