[R-pkg-devel] Workaround for code/documentation mismatch

[Duncan Murdoch]

On 10/08/2021 11:25 p.m., Andrew Simmons wrote:
> Hello,
> 
> 
> I've written two functions to emulate do while/until loops seen in other
> languages, but I'm having trouble documenting its usage. The function is
> typically used like:
> 
> do ({
>      expr1
>      expr2
>      ...
> }) %while% (cond)
> 
> so I want to document it something like:
> 
> do(expr) %while% (cond)
> do(expr) %until% (cond)
> 
> to look like the documentation for 'while' and 'if', but R CMD check
> produces a "Code/documentation mismatch" warning, complaining that the
> documentation should look like:
> 
> expr %while% cond
> expr %until% cond
> 
> So, my question is, is there a way to bypass the
> * checking for code/documentation mismatches
> portion of R CMD check, at least for one file? Some way to acknowledge that
> the code and documentation will mismatch, but that's okay.
> 

I think the answer is no.  What I'd do is name the first argument to the 
operator in a way to indicate that it must be the result of do() and the 
second to indicate it must be parenthesized (if that's a 
requirement...), e.g.

`%while%` <- function(do_expr, parenthesized_cond) { ... }

and then document as

do_expr %while% parenthesized_cond

in the \usage section, and document standard usage in the \details 
section and examples.

Duncan Murdoch