In keeping with defensive programming and input validation, I spend a lot of time enforcing and documenting types:
- using Michel Lang’s
checkmate::assert_*family and other predicates (checkmate is awesome and does double duty with testthat).
- some semi-standardized language for the users such as
#' @param x a character string, giving blah blah..
This works ok, but it always feels a little loose, and there’s some duplication in keeping the docs in line with the assertions.
I’ve just come across a couple of new cool ways of going about this:
- standardized pseudo-code inside the documentation
#' @param x [character(1)
] giving blah blah.
- @Gabor’s argufy which injects assertions and documentation based on special roxygen syntax
- @jimhester’s types and typeCheck packages, which appear to be newer and do something similar, but based on special syntax in the function preamble and body not the docs (?).
Type annotation and validation seems like something that could save a lot of time in developing packages, and make the whole experience more rigorous for users (I spend so much time browsing docs to figure out what on earth some function requires for some argument …).
- What are people’s thoughts on this?
- Is (any of) this ready for prime time and/or still actively developed?
- Is there some more documentation (vignettes)?