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

[Andrew Simmons]

When not preceded by an expression wrapped in do(), %while% would throw an
error "do while loop must begin with 'do'". The function %while% looks like

`%while%` <- function (expr, cond)
invisible(.Call(C_do.while, substitute(expr), substitute(cond),
parent.frame()))

and the corresponding C function looks like

SEXP do_dowhile(SEXP expr, SEXP cond, SEXP rho)
{
    /* we're looking for an expression of the form
       do ( expr )
       do ( { expr1 ; expr2 } )

       there must NOT be a tag on the second item, the expression within
'do'
       that is, we reject expressions of the form

       do (var = expr)
       do (var = { expr1 ; expr2 } ) */
    if (TYPEOF(expr) != LANGSXP || CAR(expr) != install("do"))
        error("do while loop must begin with 'do'");
    else if (xlength(expr) != 2 || !isNull(TAG(CDR(expr))))
        error("invalid 'expr'");

The 'do' part of the expression is irrelevant and later removed, it's only
required because it makes the syntax look more like other languages.
So the proper way to use %while% is
expr %while% cond
where expr is wrapped with do(), but I think it would be far more
understandable in the usage documentation to have it look like
do(expr) %while% (cond)

If it helps at all with context, I'll provide the R and C scripts I'm using.

On Tue, Aug 10, 2021 at 11:47 PM Hugh Parsonage <hugh.parsonage using gmail.com>
wrote:

> What is the behaviour of %while% if not preceded by an expression wrapped
> in do() ?
>
> On Wed, 11 Aug 2021 at 1:26 pm, Andrew Simmons <akwsimmo using gmail.com> 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.
>>
>>
>> Thank you!
>>
>>         [[alternative HTML version deleted]]
>>
>> ______________________________________________
>> R-package-devel using r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>>
>