[Rd] Trivial typo in help("browser")

[Martin Maechler]

>>>>> Rui Barradas 
>>>>>     on Thu, 29 Jul 2021 07:52:02 +0100 writes:

    > Hello,

    > R 4.1.0 on Ubuntu 20.04, session info below.

    > I am not an English native speaker but in help("browser"),
    > section Arguments, argument expr, there is a wrong verb
    > tense:

    > "invoked" should be "invoke", right?

    > expr An expression, which if it evaluates to TRUE the
    > debugger will invoked, otherwise control is returned
    > directly.

    > sessionInfo()   R version 4.1.0  .....

Thank you, Rui.   Indeed, there's a typo there.
I claim that it is a missing 'be':  "be invoked" almost surealy
was intended.

As we are on the R-devel mailing list, however, let's dig and learn a bit more:

Note that the *default*  is  `expr = TRUE`
which is already a bit "special" for an "expression"..

Let's try to understand what was meant --- NB a strategy I
strongly recommend even if you're somewhat experienced :

> ff <- function(x) { y <- x^2; browser("in ff():", expr = (y == 4)); y }
> ff(1)
[1] 1
> ff(2)
Called from: ff(2)
Browse[1]> debug at #1: y
Browse[2]> ls.str()
x :  num 2
y :  num 4
Browse[2]> c
[1] 4
> ff(3)
[1] 9
> 

So indeed, it does behave as I expected.
A further experiment, play with

   f2 <- function(x, e=1) { y <- x^2; browser("in ff():", expr = e); y }

shows that  'evaluates to TRUE'  is also
not as precise as it could be, and even "wrong":
 'expr = pi'  also behaves as TRUE,  and even
 'expr = NA'  behaves the same.


I don't know when/how  `expr` was introduced (probably taken
from 'S / S+' ..), but to me it seems actually somewhat a
misnomer because in that generalized sense, *every* 
argument passed to an R function is an "expression".
Instead, what counts is that a low-level as.logical(expr) is not TRUE.

So, yes, the documentation about `expr` definitely needs to be
changed.

Unless I get convincing suggestions for improvements, I'll commit

  \item{expr}{a \dQuote{condition}.  By default, and whenever not false
    after being coerced to \code{\link{logical}}, the debugger will be
    invoked, otherwise control is returned directly.}

(and also amend the formulation a bit later on the help page
 where expr is mentioned again).

Martin


    > Thanks to all R Core Team members for their great work for
    > all of us.

    > Hope this helps,

    > Rui Barradas