Implement a glossary

[jonthegeek]

Overview

Glossary added as man/glossary. Definitions are reusable for things such as function parameters or vignettes.

Closes #1658.

Test Notes/Sample Code

Notes:

@jwildfire I played with this a little, and have it mostly solved for a reusable glossary. Info from R Packages and roxygen2 help. However, I tried specifying the link like they show there, and it always applies (not selectively like the help implies), thus the links to other functions were broken. I'll dig into it a bit more + see if they have advice tomorrow. I suspect it's a bug, possibly specifically in the context of @param.

[jonthegeek]

Sadly it does appear to be a bug, which I've reported to the roxygen2 team. I'm going to move forward with the idea anyway, and assume that we'll be able to fix the handful of files one way or another. For now I'll write them in the manner that will work for documentation, and then we can later make them ALSO work for vignettes when/if they address my issue.

[jonthegeek]

@jwildfire @lauramaxwell I think I like this general idea a lot! Things to check before I push forward:

• The general process for any new parameter (or at least once that parameter will be used a second time):
  • Create a new YAML file in man/glossary, such as man/glossary/dfMetrics.yaml
  • Add a class and definition within that YAML. The definition should describe the parameter (no need to describe the class here) and how to produce it. See man/glossary/dfMetrics.yaml and man/glossary/dfResults.yaml (or any of the files where their definitions are used) for examples.
  • Add that parameter to R/aaa-shared.R with a new line: @param {paramName} `r param_from_yaml("{paramName}")` (eg, @param dfMetrics `r param_from_yaml("{dfMetrics}")`
  • Add @inheritParams shared-params to the top of the @param block in your function (and anything else that uses that param). Eventually every function will presumably include this line. Note: If you don't want to use the "default" definition of a parameter in a given function, you can include a full @param definition for that parameter, and it will override the inherited result. @inheritParams also only inherits params that are relevant to the particular function (it won't add documentation for EVERYTHING that's in the shared-params block).
  • Once we nail this down, it might make sense to split out functions to create these yamls. I can definitely imagine this being a simple package in its own right (for creating and using the definitions).
• It probably wouldn't be a bad idea to pull this PR down locally, devtools::load_all(), and ?Report_KRI to see how the definitions of dfResults and dfMetrics look in context.

Note that, if we decide to change the definitions, we only have to change them in one place (so no big deal)... but I plan to do this for all of our reused parameters, so we should probably figure out the general idea to minimize re-working.

What do you think?

[jonthegeek]

I think this is actually "done enough" for #1658. Applying the glossary will be at least one push as part of #1628, but this specific ticket shouldn't hold off until every parameter is re-documented. Let's get this one sorted out as its own PR, and THEN we can decide how to systematically apply it.

[jonthegeek]

I think this will be helpful for centralizing the documentation for df inputs and a few other unambiguous params, like vThreshold. One thing i'm finding through reviewing this is that we use the same param name for things across different functions that aren't identical, such as `strGroupColandstrType. Not sure that this a major issue, just wanted to bring it up before we go too far down this path. It seems the use for the glossary will be limited to under ten params, but centralization will still ultimately probably be super helpful.

Check out discussion #1682 for something related to this. You're definitely right, though; sometimes it makes sense to use the same name for at least slightly different meanings.

I have one more idea to experiment with for cases where there's a shared core, but possibly slightly different specifics. {roxygen2} doesn't allow you to @importParams and enhance, but I have an idea for how to make that work (so, for example, in the dfTransformed we could use a shared definition that has all the generic information, and then tack on a bit about which function we expect you to use to make it for this function).

I don't want to force unnatural rigidity or anything, but it's so easy for definitions to drift apart if we aren't vigilant, and that can be really confusing as a user. Plus it's tedious to have to describe the same basics about a parameter that we've described before.

[jonthegeek]

@lauramaxwell See what you think about this updated idea. I feel like the two functions I define in aaa-shared.R could be split off to form the heart of a fairly useful roxygen2-add-on package (in which case the calls would be something like `r glossygen::gloss_param("dfMetrics")` instead of `r gloss_param("dfMetrics")`). I might add a function or two to quickly create the yaml/Rmd helper files, too, to make the process as easy as possible (and if I ever make the package, I'd probably also add things to parse your R folder and guide you through usage).

I'd like to continue playing with this to see what's easy to use/helpful. If this makes sense to you, though, we could go ahead and merge this one, and then expand on it in future PRs.