[Rd] make file.rename return invisible

[Martin Maechler]

>>>>> Dipterix Wang 
>>>>>     on Fri, 24 Mar 2023 01:12:29 -0400 writes:

    > Dear R Core devs,

    > I wonder if it makes sense to make function file.rename return invisible? This is not a big issue, but when running in RMarkdown or knitr, this function will print results. I have to manually call invisible to hide the output from showing in the final document:

    > ```r
    > invisible(file.rename(...))
    > ```

    > Otherwise knitr will print:

    > ```
    > file.rename(...)
    > #> TRUE
    > ```

    > If this function is designed for debug/interactive use, and the return is designed to be visible so users don't have to manually print, would it be possible to add an option to suppress the printing? 

Well, all (or just most?) of these  file.*() file manipulation
functions have been designed to return logicals ... and making a
return value invisible is rather the exception than typical in R.

And, why should (your own solution)

    invisible(file.rename(from, to))

not be sufficient?  I think it's much more expressive than e.g.,

    file.rename(from, to, invisible=TRUE))


Note that very safe use (in scripts run automatically, ..) should
happen inside

    if (!file.rename(a,b))
       stop("Could not successfully rename ", a, " to ", b)

anyway... and indeed it's much much less confusing for people
debugging such code that functions behave normally, i.e., the
user / programmer / debugger sees  TRUE or FALSE when evaluating
the function call.

Martin Maechler
ETH Zurich  and   R Core team