[Rd] c() documentation after change; 'recursive' in "base" methods

[Martin Maechler]

>>>>> Suharto Anggono Suharto Anggono via R-devel <r-devel at r-project.org>
>>>>>     on Wed, 19 Apr 2017 22:50:41 +0000 writes:

    > In R 3.4.0 RC, argument list of 'c' as S4 generic function has become
    > (x, ...) .
    > However, "S4 methods" section in documentation of 'c' (c.Rd) is not updated yet.

Thank you, I've committed a change (72564 & 72565).

    > Also, in R 3.4.0 RC, 'c' method of class "Date" ('c.Date') is still not explicitly documented.

yes, but that's true for other S3 methods, see below.

This is a bigger issue.  Thank you for raising it!  Look at

-------------------------------- R code --------------------------------------

(mc <- methods("c"))
## [1] c.bibentry*       c.Date            c.difftime        c.noquote         c.numeric_version
## [6] c.person*         c.POSIXct         c.POSIXlt         c.warnings
## and from `lcNSnm` below, you can see that these are from 'base',
## apart from {bibentry, person} which are from 'utils'
lc <- lapply(mc, function(nm) { f <- getAnywhere(nm) })
names(lc) <- sapply(lc, `[[`, "name")
str(lcwh <- lapply(lc, `[[`, "where"))
lcNSnm <- sub("^namespace:", '', sapply(lcwh, function(v) v[length(v)]))
lcNS <- lapply(lcNSnm, asNamespace)
str(lcMeths <-
        sapply(names(lcNS), function(n) get(n, envir=lcNS[[n]], inherits=FALSE),
            simplify = FALSE))
## $ c.bibentry       :function (..., recursive = FALSE)
## $ c.Date           :function (..., recursive = FALSE)
## $ c.difftime       :function (..., recursive = FALSE)
## $ c.noquote        :function (..., recursive = FALSE)
## $ c.numeric_version:function (..., recursive = FALSE)
## $ c.person         :function (..., recursive = FALSE)
## $ c.POSIXct        :function (..., recursive = FALSE)
## $ c.POSIXlt        :function (..., recursive = FALSE)
## $ c.warnings       :function (..., recursive = FALSE)

-------------------------------- ...... --------------------------------------

and from these, only the 'noquote' method has a "\usage{ . }"
documentation.

The reason actually is that I had *wanted* to consider
__removing__ the 'recursive' argument from most of these S3 methods,
since all but  c.numeric_version()  completely disregard it and
it would be nicer if they did not have it.

HOWEVER, if it is removed and a user / code has

    val <- c(...., recursive = r)

then 'recursive' will become part of 'val' which is not desirable.

I had never thought more about this and if we should try or not to
remove it from the S3 methods in all those cases it is unused
... hoping that callers would also *not* set it.

As _one_ consequence I had decided rather *not* documenting it
for the S3 methods where it is (still ?!) part.

Martin