Documentation: Centralized issue for all things roclet-related for function argument default/permitted values

[zdz2101]

Please select a category the issue is focused on?

Function Documentation

Let us know where something needs a refresh or put your idea here!

In summary, in much of our roxygen documentation for function argument values we have inconsistencies on how to handle/display default and permitted values. Our best lead has been to implement a roxygen roclet to address these instances.

We have closed many issues along the way related to this topic but the remaining open issues are as follows:

From admiral:
#1402
#1590 (the beginning of the roclet)

From admiraldev:
pharmaverse/admiraldev#11
pharmaverse/admiraldev#64
pharmaverse/admiraldev#166
pharmaverse/admiraldev#270

From admiralonco:
pharmaverse/admiralonco#130 (lots of discussion was had here)

[ddsjoberg]

@zdz2101 and @ddsjoberg discussed

• Rather than a custom roclet, the permitted values and default values will be added under the @param tag.
• The existing values will need to be reviewed for consistent italics.

We also discussed the "searchability" issue. We discussed adding a section to each function's help file listing the variables that can be created with that function. But thinking about it a bit more, I think an article would be best with an interactive and searchable table that lists the function, ADaM domain, and the variable name. The table can be searched or filtered by the admiral function name (helpful when you want to see what variables are commonly created by a function), and you can also filter by a variable name to quickly find the function to use to derive the variable.

(the final table can obviously made to be much cuter)

dplyr::tribble(
  ~fun, ~dataset, ~colname,
  "derive_a", "adsl", "AGE",
  "derive_a", "adae", "SUBJID",
  "derive_b", "adae", "AESEQ",
  "derive_b", "adae", "AETOX",
) |> 
  gt::gt() |> 
  gt::opt_interactive(
    use_sorting = TRUE,
    use_search = TRUE, 
    use_filters = TRUE,
    use_resizers = TRUE,
    use_highlight = TRUE
  )