[Rd] Revisions of the S4 classes software + ?Documentation

[John Chambers]

Some changes to the implementation of S4 classes in the methods package
will be committed to the r-devel version, probably later today.  They
should be largely back-compatible (exception noted below) but they are
fairly extensive, so this is an advance notice.

The changes form the first of a two-stage change aimed at making the
implementation more consistent with R semantics, in particular with
namespaces.  The second stage will involve changes to generic functions
and methods software.

Mainly the changes move towards using only class definition objects and
generic function objects to define classes and methods, as opposed to
the model involving metadata and databases, as in the green book.

For classes, the implication is that class relationships are inferred
from the class definition objects.

Unless you have programmed explicitly with metadata objects (hopefully
not!) the changes should be largely compatible, but the point of this
mail is to alert owners of packages to watch for exceptions.

One known incompatibility has to do with setIs relations that extend the
basic datatypes.  For example, 
  setClass("maybeNumber")
  setIs("numeric", "maybeNumber")
  setIs("logical", "maybeNumber")
defines a new class and says that "numeric" and "logical" extend it.

Once the new code is committed, this will fail, because the definition
of "numeric" is sealed, and cannot be revised.  (That didn't matter
before, since the relation was stored in special metadata objects.)

A special mechanism has been added for this kind of example--the
definition of a union of classes.  See ?setClassUnion once the new code
has been committed.  IMO the new version is clearer--the three lines
above turn into
  setClassUnion("maybeNumber", c("numeric", "logical"))

At the same time, a new Documentation.Rd file will be added with some
online help about documentation for classes and methods--how to get it
and how to write it.  Do ?Documentation.  (The contents will grow over
time.)

John
-- 
John M. Chambers                  jmc at bell-labs.com
Bell Labs, Lucent Technologies    office: (908)582-2681
700 Mountain Avenue, Room 2C-282  fax:    (908)582-3340
Murray Hill, NJ  07974            web: http://www.cs.bell-labs.com/~jmc