[R] documentation of intersect() on string vector and num vector and on duplicated elements

[Peng Yu]

On Wed, Dec 2, 2009 at 5:36 PM, Peter Ehlers <ehlers at ucalgary.ca> wrote:
>
> Peng Yu wrote:
>>
>> On Wed, Dec 2, 2009 at 3:51 PM, David Winsemius <dwinsemius at comcast.net>
>> wrote:
>>>
>>> On Dec 2, 2009, at 4:33 PM, Peng Yu wrote:
>>>
>>>>> intersect(c(1,3,2),c('1','3'))   # note x is numeric and y is character
>>>>
>>>> [1] "1" "3"
>>>>
>>>> Apparently, intersect() treats num as string. But this is not
>>>> documented in the help. Could somebody add it in the future version of
>>>> R?
>>>
>>> It is documented that intersect will return a value of that is same mode
>>> as
>>> its "y" argument. How could it be any more clear?
>>>
>>>> Also according to the help, the argument should not have duplicated
>>>> elements.
>>>
>>> That's not what my help page says. It says that "conceptually" they won't
>>> have them, but immediately thereafter it says:
>>> "Details
>>> Each of union, intersect, setdiff and setequal will discard any
>>> duplicated
>>> values in the arguments, and they apply as.vector to their arguments (and
>>> so
>>> in particular coerce factors to character vectors)."
>>>
>>> Unfortunately, R does not have a package that will ensure that users will
>>> read the help pages carefully.
>>
> ----------------------------
>>
>> I didn't read Details. Because I was interested in the arguments. The
>> problem of some R document is that some information should gathered
>> together are spread into multiple places. In particular, in the help
>> of intersect, the first line of 'Details' should be merged with
>> 'Argument' to make the help page clear and easy to read.
>
> ----------------------------
>
> I take very strong exception to this suggestion and to the
> whining tone of the comment. If an R user can't be bothered
> to read *all* of a help page, then that's his problem, not R's.
>
> Since it is IMHO too common in this forum to see complaints
> about the documentation, let me just say this:
> I personally find the documentation of (base) R very, very
> good to excellent and I think that R-Core deserve a big
> pat on the back for their efforts to be as informative as
> possible with the help system. Probably my most used
> R function is "?" and I particularly like the
> arguments/details/value etc layout.

If the document can be improved, it doesn't hurt to make the document
even better, right?