use roxytypes and roxylint packages

[dgkf]

I've made a couple contributions so far where the vast majority of the review process circles around formatting of params. Admittedly I'm new to this convention, but I'm finding it excessively burdensome and sensitive.

As a newcomer developer to this project the easiest solution is not to document internal functions or to introduce as few supporting functions as possible, which probably means we've incentivized the wrong behaviors.

To help lower the barrier to entry, I'd like to propose a few paths that might lighten this load. In decreasing order of the amount of work it would take to implement:

Roxygen2 Solution

The most idiomatic solution would be to build a supporting package that provides a roxygen2 tag. We could hash out the syntax a bit, but I would propose something like:

#' @typed <var>: <type>
#'   <desc>

Handling it this way, we could expose options that are set in the DESCRIPTION to configure behaviors.

Config/<package>:
  list(require_full_stop = TRUE, format = "@param {var} (`{type}`)\cr {desc}")

This would help shift formatting mishaps into documentation errors or warnings to lighten some of the review overhead and would make it much easier to tweak formatting.

If there's interest in having something like this, I don't mind devoting a couple days to fleshing it out. I think it could be a relatively quick win. As much as I'm a skeptic of trying to wrangle R's dynamic typing with hints, I'd be happy to chip away at the burden this introduces by automating some of these mundane formatting concerns.

@eval Solution

If we don't want to go off and build a supporting package, an alternative solution would be just to add a little internal helper function. Something as simple as:

#' @param t `r type("character")` description
type <- function(t) paste0("(`", t, "`)\cr ")

or

#' @eval typed("t", "character", "description")
typed <- function(var, type, desc) paste0("@param ", var, " (`", type, "`)\cr ", desc)

Would go a long way to enforcing consistency programmatically. The examples above are trivial implementations, but a more comprehensive solution could enforce the casing and punctuation to make compliance a documentation-time warning/error instead of adding manual review overhead.

Less-strict @params notation

Finally, as a "least-work" solution, just improving consistency and perhaps being a bit less sensitive would go a long way toward easing the developer overhead.

Currently we require a syntax of:

@param <var> (`<type>`)\cr sentence description.
              ^~~~~~~~ ^~ ^^                   ^
              |        |  |lowercase           full stop
              |        |  |
              |        |  + exactly one space
              |        |
              |        + Rd TeX carriage return
              |
              + markdown inline code type

This is a unique mix of markdown, Rd TeX, and tidyverse style with its own unique quirks. As a "least-work" approach, just relaxing these requirements or reducing the uniqueness of it would be a welcome change. I would propose to reduce flavor-mixing by disregarding the \cr and adopting the tidyverse style guide for sentence casing. If we're going to be particular, we could at least try not to be unique.

On a related note, I would also lean toward the tidyverse convention for titles, which uses sentence-case instead of title-case to reduce the uniqueness of the package conventions.

[dgkf]

I went ahead and fleshed out the roxygen2 typed parameter definitions as a separate package.

https://github.com/dgkf/roxytypes

[yonicd]

There is already a solution for templating and auto populating roxy docs {sinew}.

[dgkf]

There is already a solution for templating and auto populating roxy docs {sinew}.

This is super cool! I’d be totally fine using something other than what I slapped together- frankly I just went down the rabbit hole exploring the idea. By the time I was satisfied it was very little effort to tie a package shaped bow on it.

In sinew, I saw that you can configure the template that it’s used, but I couldn’t tell from a skim of the docs whether it does any checking on conformance to that style. Is that part of its feature set?

[danielinteractive]

Thanks a lot @dgkf for putting the options together, and also the first prototype. Also thanks @yonicd for the pointer to sinew!
I guess one or the other package solution extending roxygen2 would be awesome to have. We definitely have quite a lot of packages (far beyond just this mmrm one here) that use this convention, so it would be good to leverage broadly.
Maybe you can check if we can use or contribute to sinew, or if we need a new one?

[yonicd]

Contribution to sinew is always welcome. It certainly makes pkg dev life simpler for users.

[danielinteractive]

I think we can next try to use roxytypes and roxylint packages here