[Rd] binary form of is() contradicts its unary form

[Martin Maechler]

>>>>> Iñaki Úcar <i.ucar86 at gmail.com>
>>>>>     on Thu, 30 Nov 2017 14:32:12 +0100 writes:

    > 2017-11-30 14:13 GMT+01:00 Suzen, Mehmet <mehmet.suzen at gmail.com>:
    >> On 30 November 2017 at 14:04, Iñaki Úcar <i.ucar86 at gmail.com> wrote:
    >>> 
    >>> Am I supposed to read every reference on a man page just to know what
    >>> to expect from a function?
    >>> 
    >> 
    >> If the reference is from John Chamber, you are supposed to read it.
                       (note: it is  Chamber*s* )

    > As a joke, it's funny.

    >> It is not always possible for maintainers to document everything on a man page.

Correct.  But honestly, I'm not even sure if John Chambers'
change to the help page last October dropped that description of
is() on purpose.   In my eyes, the main change to the help page was to
deemphasize the use of setIs(), and document that separately
(for experts, whereas the doc for is() and extends() is for mere useRs) :

--------------------------------------------------------------------------------
r71460 | jmc | 2016-10-06 20:23:19 +0200 (Thu, 06. Oct 2016) |

   M src/library/methods/man/as.Rd
   M src/library/methods/man/is.Rd
   A src/library/methods/man/setAs.Rd
   A src/library/methods/man/setIs.Rd
   M src/library/methods/man/setMethod.Rd

Further changes to separate user-relevant doc. for is(), as().
Change examples in setMethod() to be acceptable R code 
....
--------------------------------------------------------------------------------

    > My only point is that Hervé's concern is perfectly legitimate given
    > the output of "?is". 

I'd tend to agree -- but am *not* volunteering to fix it, currently.

    > Whether the inconsistency is in the behaviour of
    > the function or in the documentation, that I don't know. Personally, I
    > think that having two functions (is, extends) with exactly the same
    > output wouldn't be very practical. 

They have different "input", (or---better language-- 'argument's) :

	is(<object>, ..)
   extends(<class>,  ..)

I would also tend to agree with Hervé that the binary and unary
uses of is()  "should be" consistent, as they are for S4, where
indeed, is() stems from.

    > But it's a fact that the difference
    > is not currently addressed in the man page.

correct, too.

    > Iñaki