Documentation: Examples of when to use Default and Permitted Values

[bms63]

Please select a category the issue is focused on?

Function Documentation

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

A good part of our function documentation have default and permitted values listed in the function arguments. However, this is not completely adopted across admiral.

To remedy this:

• Update the Programming Strategy to have best practices on when and how Default to be used.
• Update the Programming Strategy to have best practices on when and how Permitted Values are to be used.
• General Issue: Identify the functions and corresponding function argument documentation that need these updates and list out. #166
• Update function documentation for Default per programming strategy
• Update function documentation for Permitted Values per programming strategy

[rossfarrugia]

This came up in our admiralonco tester feedback:

Comparing for example https://pharmaverse.github.io/admiralonco/test/reference/derive_param_bor.html#arguments with https://pharmaverse.github.io/admiralonco/test/reference/derive_param_confirmed_bor.html#arguments we got the feedback:
the "Arguments" documentation is not same across all functions: for eg "derive_param_bor" had provided if the parameter is required or not. but if we look into consistency across all references to provide permistted values, optional or not, defualt values.

Fully agree with making this update to include them consistently across all functions.

[rossfarrugia]

See summary of discussions pharmaverse/admiralonco#130 as these updates from admiralonco will also be needed across admiral functions. @bms63 will summarize these in the programming strategy so we have a clear guide to follow: #64

[bms63]

Moving this to admiraldev

[zdz2101]

Created a table of functions in admiral (43 impacted) which has at least 1 argument/param that contains the following in the roxygen block:
*Default*
*Permitted Values*

functions_to_check.csv

Table contains 4 columns:

• the file that contains the function
• the function in question
• logical for if it contains default
• logical for if it contains permitted

[bms63]

omg @zdz2101 thank you for taking this on!!!

[bms63]

@zdz2101 can you break this into separate issues:

1. Clean up functions in admiral and admiraldev based on guidance developed in programming strategy (contingent on updates from Adam)
2. Create the guidance itself in the programming strategy