doc updates

Author: lawremi

R/S4.R

@@ -4,9 +4,10 @@
 #' an S7 class that does not extend an S4 class, or an S3 class created by
 #' [new_S3_class()], you need to call `S4_register()` once. Classes created by
 #' [new_class()] with an S4 parent are registered automatically.
-#' Use `S4_register_contains()` when you want an S4 class to extend an S7 class
-#' with `contains=`. This registers the S7 class as an old class with known
-#' attributes so that S7 properties are represented as S4 slots.
+#'
+#' @section Details:
+#' ```{r child = "man/rmd/S4-registration.Rmd"}
+#' ```
 #'
 #' @param class An S7 class created with [new_class()], or, for
 #'   `S4_register()` only, an S3 class created with [new_S3_class()] or an S7

R/class.R

@@ -14,9 +14,10 @@
 #'   with this name, i.e. `Foo <- new_class("Foo")`. This object both represents
 #'   the class and is used to construct new instances of the class.
 #' @param parent The parent class to inherit behavior from.
-#'   There are three options:
+#'   There are four options:
 #'
 #'   * An S7 class, like [S7_object].
+#'   * An S4 class, like the result of [methods::getClass()].
 #'   * An S3 class wrapped by [new_S3_class()].
 #'   * A base type, like [class_logical], [class_integer], etc.
 #' @param package Package name. This is automatically resolved if the class is

man/S4_register.Rd

@@ -1,63 +1,63 @@
-When an S7 class extends an S4 class, `new_class()` automatically registers the
-new class with S4. After that, an S4 generic with a method for `Parent` will
-dispatch on a `Child` instance:
+`new_class()` can use an S4 class as its parent. The S4 class can be supplied
+as a class definition, such as `methods::getClass("Parent")`, or as a class
+generator returned by `methods::setClass()`. The S4 parent slots become S7
+properties on the new S7 class.
+
+When an S7 class extends an S4 class, `new_class()` automatically registers an
+S4 old class for the S7 class. This lets S4 generics dispatch through the S4
+parent:
 
 ```r
-setMethod("g", "Parent", function(x) ...)
-g(child) # uses Parent method if no more specific Child method exists
-```
+methods::setClass("Parent", slots = list(x = "numeric"))
+Child <- new_class("Child", methods::getClass("Parent"),
+  properties = list(y = class_character)
+)
 
-But the method receives the original S7 object, not a formal S4 instance, so
-this approach is a compatibility bridge, not full substitutability.
+methods::is(Child(x = 1, y = "a"), "Parent")
+```
 
 Things that work reasonably:
 
+* S4 dispatch inherits through the S4 parent. An S4 generic with a method for
+  `Parent` can dispatch on a `Child` object.
 * `methods::is(child, "Parent")` returns `TRUE`.
-* S4 dispatch inherits through `Parent`.
-* `methods::validObject(child)` validates the S4 parent slots through S4 and
-  recursively validates S7 properties and class validators through S7.
-* `methods::slotNames(child)` reports the S4 parent slots. S7 extension
-  properties are not registered as formal S4 slots.
-* `methods::slot(child, "x")` works for stored attributes, but bypasses the S7
-  property layer.
-* `child@x` works through S7 property access. With the current oldClass
-  representation, the object is not S4-bit so `@` can dispatch to S7's
-  `@.S7_object` method. If S7 objects that extend S4 classes are represented
-  as S4-bit objects in the future, R's `@` primitive will need to dispatch
-  before taking the S4 slot-access path.
-* `methods::initialize(child, ...)` works for reinitializing an existing S7
-  object through S4 code. This is most useful for inherited S4 methods that
-  update parent slots or data parts. Values are routed through S7 property
-  assignment, so S7 metadata and validation are preserved.
-* `as(child, "Parent")` can produce a real S4 `Parent` object containing the
-  parent slots.
-
-Likely brittle or incompatible with S4-method assumptions:
-
-* `isS4(child)` is `FALSE` with the current oldClass representation. This
-  avoids advertising formal S4 object invariants that S7 objects do not
-  satisfy. S4 code is still exposed to S3-compatible, non-scalar `class()`
-  vectors through the oldClass bridge.
-* `class(child)` is length greater than 1, for example
-  `c("Child", "S4/Parent", "S7_object")`. This can break S4 code that treats
-  `class()` as a scalar class name. Code that needs a scalar primary class
-  name should use `class(x)[1L]`, or `methods::class1(x)` once that helper
-  has been made public.
-* Methods that access slots with `methods::slot()` and `methods::slot<-()`
-  bypass the S7 property layer. This is similar to deriving from an S3 class
-  whose methods use `attr()` and `attr<-()` directly. Overriding S4 slots is
-  therefore discouraged.
-* Calls like `methods::new(class(x)[1L], ...)` or
-  `methods::new(class1(x), ...)` construct a new S4 object from S4's class
-  definition. For an S7 class registered with S4, the result can satisfy
-  `inherits(object, "S7_object")` through the S4 oldClass graph while still
-  lacking the `S7_class` attribute. Such objects are not S7 instances, and
-  `methods::validObject()` will reject them. Code that is updating an
-  existing object should prefer `methods::initialize(x, ...)`, which gives
-  S7's S4 `initialize()` method a chance to preserve S7 metadata.
-
-In summary, inherited S4 methods must be written against the "registered
-oldClass that preserves the S4 parent" contract, not the stricter "formal S4
-instance" contract. They should use a scalar primary-class helper where
-appropriate and avoid `slot()` and `slot<-()` when they need S7 property
-management to apply.
+* S4 parent slots are available as S7 properties, so `prop(child, "x")` and
+  `child@x` use the S7 property path.
+* `methods::slot(child, "x")` can read stored S4 parent slots and stored S7
+  properties. Direct slot access bypasses custom S7 property behavior, so S4
+  code should use it only for slots it owns.
+* `methods::validObject(child)` checks S4 slot types and recursively runs S7
+  property validation and S7 class validators.
+* `methods::initialize(child, ...)` can reinitialize S7 objects from S4 code.
+  Unnamed S7, S4, and S3-data-part arguments contribute their known
+  properties or slots; later arguments override earlier arguments, and named
+  arguments override unnamed ones.
+* `methods::as(child, "Parent")` and `convert(child, to = Parent)` can produce
+  a real S4 object for the S4 parent class.
+
+Caveats:
+
+* An S7 object that directly extends S4 is currently represented as an S3
+  old-class object, not as an S4-bit object, so `isS4(child)` is `FALSE`.
+  This avoids advertising full S4 object invariants that the object does not
+  satisfy.
+* The S3 class vector is not scalar. S4 code that needs one primary class name
+  should use `class(x)[1L]`, or `methods::class1(x)` if available.
+* `methods::new(class(x)[1L], ...)` creates a fresh S4 object from the S4 class
+  definition. For an S7 class registered with S4, that object can inherit from
+  `S7_object` through the old-class graph while lacking the `S7_class` slot or
+  attribute that makes it an S7 object. Code that updates an existing object
+  should prefer `methods::initialize(x, ...)`.
+* S4 methods that call `methods::slot<-()` can bypass S7 property setters and
+  ordinary S7 validation. Call `methods::validObject()` after such updates when
+  the object should satisfy the S7 class contract.
+* Properties with custom getters or setters cannot be exposed as S4 slots. An
+  S7 class that extends S4, or that is intended to be extended by S4, must use
+  stored properties for the properties that need to cross the S4 boundary.
+* `NULL` properties are stored internally using the same sentinel that S4 uses
+  for `NULL` slots. `prop()`, `@`, and `methods::slot()` translate this back to
+  `NULL`; code that reads raw attributes should treat the representation as an
+  implementation detail.
+
+S4 classes can also extend S7 classes with `S4_register_contains()`. See
+`S4_register()` for details.