[Rd] On modes, types and R documentation

[Martin Maechler]

>>>>> "BaRow" == Barry Rowlingson <b.rowlingson at lancaster.ac.uk>
>>>>>     on Fri, 26 Sep 2008 07:50:33 +0100 writes:

    BaRow> 2008/9/25 Kingsford Jones <kingsfordjones at gmail.com>:
    >> 
    >> Try
    >> 
    >> ?type
    >> 
    >> which correctly guesses the user is looking for the
    >> 'typeof' page.
    >> 
    >> Or even
    >> 
    >> example(type)
    >> 
    >> Also, after a brief introduction, the R Language
    >> Definition document begins with a discussion of types.
    >> 
    >> Kingsford Jones


    BaRow>  But if, oh if, we could start R from scratch, would the documentation
    BaRow> contain such gems as:


    BaRow>  "value: a character string giving the desired mode
    BaRow> or 'storage mode' (type) of the object."

Barry, thank you, and we're very often very thankful for patches
to the docs...  I see you found this on help(mode) and there, it
is documenting "value" for

		mode(x) <- value
and	storage.mode(x) <- value

and for that reason got to the above gem.

You probably know that 'type' / 'typeof' is an R-specific
(non-S) concept which has been part of R even before it's
pre-alpha version got a version number.  It returns the basic
R-internal "SEXP" type. 
storage.mode is similar (an old S concept), but slightly
different:

  > storage.mode
  function (x) 
  switch(tx <- typeof(x), 
	 closure = , builtin = , special = "function", 
	 tx)

but I agree equivalent for almost all purposes.
So maybe one should drop the  '(type)'  part in the above gem.

-----

    BaRow> """ 
    BaRow> As storage mode "single" is only a pseudo-mode in
    BaRow> R, it will not be reported by mode or storage.mode:
    BaRow> use attr(object, "Csingle") to examine this. However,
    BaRow> mode<- can be used to set the mode to "single", which
    BaRow> sets the real mode to "double" and the "Csingle"
    BaRow> attribute to TRUE. Setting any other mode will remove
    BaRow> this attribute.

Ah. I found this is cited from the 'Details' section of
help(mode).  Well, I could argue that this paragraph and almost
all mentioning of "single" on that help page should be dropped,
and only one link to  help(single) should remain.

One reason it's there, may be because this part is different
from S/S-plus.  I don't see why an average user should see any
mention of "single" at all.


    BaRow> Looking at the R docs for typeof and mode it seems to
    BaRow> refer to modes, types, storage modes, (storage)
    BaRow> modes, 'storage mode' (type)s, real modes,
    BaRow> pseudo-modes and internal types. Confused? Clearly
    BaRow> people are!

:-) nice list ! 

If we eliminated the above "single" paragraph, we'd eliminate
"pseudo-mode" and "real mode"...

Otherwise, I'm sure you know that

 type         = internal type
 storage.mode = an almost equivalent union (of 'type')
 mode         = an S/S-plus compatible version of storage.mode

but for many years, we've now had class() which for the average
user should be sufficient in 98% of the cases, and in the other 
2% , typeof() would provide the extra info.

Martin