Check package function arguments for order (important to least important), consistent naming, and pipe compatability: if function returns same class as input, it should be the first argument

check_package_arguments.R

Library(dplyr)

# Which package to check
trias_namespace <- asNamespace("trias")

# Character vector of all functions and their arguments, print method of base ls with str() on every object
trias_fns_args <- capture.output(utils::lsf.str(trias_namespace))

# Extract the functions
trias_functions <- stringr::str_extract(trias_fns_args, ".+(?= :)") %>%
  .[!is.na(.)]
# Extract their arguments
trias_arguments <-
  stringr::str_extract_all(
    stringr::str_c(trias_fns_args, collapse = " "),
    stringr::regex("(?<=function \\().*?\\)", dotall = TRUE, multiline = TRUE)
  ) %>%
  purrr::map(~ stringr::str_remove(.x, "\\)$")) %>%
  purrr::map(~ stringr::str_split(.x, stringr::fixed(","))) %>%
  purrr::map(~ purrr::map(.x, stringr::str_squish)) %>%
  purrr::flatten()


# Create a tibble with one row per argument, also column with the arguments
# witout defaults (not foolproof)
trias_fns_args_tbbl <- 
  tibble(trias_functions, trias_arguments) %>% 
  tidyr::unnest(trias_arguments) %>% 
  mutate(arg_only = stringr::str_remove(trias_arguments, " .+$"))

# Cluster based on string disntance
hc <- 
  stringdist::stringdistmatrix(trias_fns_args_tbbl$arg_only,
                             trias_fns_args_tbbl$arg_only) %>% 
  as.dist() %>% 
  hclust(method = "average")

# Reorder our tibble so the most similar arguments are together
trias_fns_args_tbbl[hc$order, ]


# now check for output ----------------------------------------------------

# f <- gbif_verify_keys
# rd <- tryCatch(tools::parse_rd(f), error=function(e)NULL)
# errors WILL arise, so handle them here ...
# pars <- tools:::.Rd_get_metadata(rd, "arguments")

verf_gb <- tools::parse_Rd("man/gbif_verify_keys.Rd")

verf_gb[purrr::map_lgl(verf_gb, ~attr(.x, which = "Rd_tag") == "\\value")] %>% 
  as.character()

extract_rd_value <- function(rd_file) {
  rd_obj <- tools::parse_Rd(rd_file)
  
  rd_obj[purrr::map_lgl(rd_obj, ~attr(.x, which = "Rd_tag") == "\\value")] %>% 
    # as.character()
    unlist
}

trias_output_values <- 
  list.files("man", full.names = TRUE, include.dirs = FALSE) %>% 
  .[stringr::str_ends(., ".Rd")] %>% 
  purrr::map(extract_rd_value)

# Create a tibble with the output value (per documentation) per exported
# function
output_values_tbbl <-
  tibble(
    filename = list.files("man", include.dirs = FALSE, pattern = "\\.Rd$"),
    value = purrr::map_chr(trias_output_values, paste, collapse = "")) %>% 
  mutate(function_name = fs::path_ext_remove(filename))

# Cluster based on string disntance
hc_value <- 
  stringdist::stringdistmatrix(output_values_tbbl$value,
                               output_values_tbbl$value) %>% 
  as.dist() %>% 
  hclust(method = "average")

# Reorder our tibble so the most similar arguments are together
output_values_tbbl[hc_value$order, ] %>% 
  filter(value != "")

## get first arguments of functions
first_args_tbl <- tibble(trias_functions, trias_arguments) %>%
  mutate(first_argument = purrr::map_chr(trias_arguments, ~
    .x[[1]]))

# Merge them, so we can get the most similar description, and see the first
# function argument
left_join(output_values_tbbl,
          first_args_tbl,
          join_by(function_name == trias_functions))[hc_value$order, ] %>% 
  select(function_name, first_argument, value) %>% 
  View("Similar output values")

See also https://gist.github.com/PietrH/4185804a84975ade2ff938fa64a303a8