From maechler at stat.math.ethz.ch  Thu Nov 30 15:45:03 2017
From: maechler at stat.math.ethz.ch (Martin Maechler)
Date: Thu, 30 Nov 2017 15:45:03 +0100
Subject: [Rd] binary form of is() contradicts its unary form
In-Reply-To: <CALEXWq3_N5OZvPTC4tuCVRPsPSNV+SHYHiqk66FZczLmdWdohw@mail.gmail.com>
References: <5A1EF8DB.6080401@fredhutch.org>
 <CAPtbhHzXe3=EBW6wwyx1Hh158qjBrC0vfFbh4+o3bRZTC+c5Kw@mail.gmail.com>
 <5A1F0EB3.7090508@fredhutch.org>
 <CAPtbhHws5Fydk0AHeq3Urh9qEZ4XM0C-BJtoRvUpnStb33G=mg@mail.gmail.com>
 <5A1F1C60.9080506@fredhutch.org>
 <CAPtbhHy4=U8V-XRtg63=eS4PAWgqQM6=-xnSmVSgdPFbuv8dxw@mail.gmail.com>
 <CALEXWq3yQadGRyhUmcJ9p7kG=2Jf55=8v-U6tNukRWnZ6_Tpdw@mail.gmail.com>
 <CAPtbhHx+mQtMwVoTYqi4yCFf8EujMdzH+-Ped=Q02uxDhfEP-w@mail.gmail.com>
 <CALEXWq3aHdFmpFq+ehGVGddewXtq1GsS0y5R_5HpCu2eWidtDg@mail.gmail.com>
 <CAPtbhHzO_S-PYMjnXXLO3E9=jakrLtbwzuKCfaYMqigYX=Wndg@mail.gmail.com>
 <CALEXWq3_N5OZvPTC4tuCVRPsPSNV+SHYHiqk66FZczLmdWdohw@mail.gmail.com>
Message-ID: <23072.6511.695333.220629@stat.math.ethz.ch>

>>>>> 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



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