Documentation polishing

R/S3.R

@@ -2,6 +2,7 @@
 #'
 #' To use an S3 class with S7, you must explicitly declare it using
 #' `new_S3_class()` because S3 lacks a formal class definition.
+#' (Unless it's an important base class already defined in [base_s3_classes].)
 #'
 #' # Method dispatch, properties, and unions
 #' There are three ways of using S3 with S7 that only require the S3 class
@@ -180,8 +181,19 @@ validate_data.frame <- function(self) {
   }
 }
 
+#' S7 wrappers for key S3 classes
+#'
+#' @description
+#' S7 bundles [S3 definitions][new_S3_class] for key S3 classes provided by
+#' the base package:
+#'
+#' * `class_data.frame` for data frames.
+#' * `class_Date` for dates.
+#' * `class_factor` for factors.
+#' * `class_POSIXct` for `POSIXct` date-times.
+#'
 #' @export
-#' @rdname base_classes
+#' @name base_s3_classes
 #' @format NULL
 #' @order 3
 class_factor <- new_S3_class("factor",
@@ -192,7 +204,7 @@ class_factor <- new_S3_class("factor",
 )
 
 #' @export
-#' @rdname base_classes
+#' @rdname base_s3_classes
 #' @format NULL
 #' @order 3
 class_Date <- new_S3_class("Date",
@@ -203,7 +215,7 @@ class_Date <- new_S3_class("Date",
 )
 
 #' @export
-#' @rdname base_classes
+#' @rdname base_s3_classes
 #' @format NULL
 #' @order 3
 class_POSIXct <- new_S3_class("POSIXct",
@@ -214,7 +226,7 @@ class_POSIXct <- new_S3_class("POSIXct",
 )
 
 #' @export
-#' @rdname base_classes
+#' @rdname base_s3_classes
 #' @format NULL
 #' @order 3
 class_data.frame <- new_S3_class("data.frame",

R/base.R

@@ -54,13 +54,11 @@ str.S7_base_class <- function(object, ..., nest.lev = 0) {
   print(object, ..., nest.lev = nest.lev)
 }
 
-#' Base classes
+#' S7 wrappers for base types
 #'
 #' @description
-#' These classes represent base types allowing them to be used within S7.
-#' There are three categories: base types, unions types, and key S3 classes.
-#'
-#' Base types:
+#' The following S7 classes represent base types allowing them to be used
+#' within S7:
 #'
 #' * `class_logical`
 #' * `class_integer`
@@ -73,21 +71,15 @@ str.S7_base_class <- function(object, ..., nest.lev = 0) {
 #' * `class_function`
 #' * `class_environment` (can only be used for properties)
 #'
-#' Union types:
+#' We also include three union types to model numerics, atomics, and vectors
+#' respectively:
 #'
 #' * `class_numeric` is a union of `class_integer` and `class_double`.
 #' * `class_atomic` is a union of `class_logical`, `class_numeric`,
 #'   `class_complex`, `class_character`, and `class_raw`.
 #' * `class_vector` is a union of `class_atomic`, `class_list`, and
 #'   `class_expression`.
 #'
-#' Key S3 classes:
-#'
-#' * `class_data.frame`
-#' * `class_Date`
-#' * `class_factor`
-#' * `class_POSIXct`
-#'
 #' @order 0
 #' @name base_classes
 #' @return S7 classes wrapping around common base types and S3 classes.

R/class-spec.R

@@ -12,6 +12,7 @@
 #'   * A base class, like [class_logical], [class_integer], or [class_double].
 #'   * A "special", either [class_missing] or [class_any].
 #' @param arg Argument name used when generating errors.
+#' @keywords internal
 #' @export
 #' @return A standardised class: either `NULL`, an S7 class, an S7 union,
 #'   as [new_S3_class], or a S4 class.

R/method-introspect.R

@@ -1,14 +1,15 @@
-#' Retrieve a method for an S7 generic
+#' Find a method for an S7 generic
 #'
-#' `method()` takes a generic and signature and retrieves the corresponding
-#' method. This is rarely needed because most of the time you'll rely on the
-#' the generic, via [S7_dispatch()], to find and call the method for you.
-#' However, this introspection is useful if you want to see the implementation
-#' of a specific method.
+#' `method()` takes a generic and class signature and performs method dispatch
+#' to find the corresponding method implementation. This is rarely needed
+#' because you'll usually rely on the the generic to do dispatch for you (via
+#' [S7_dispatch()]). However, this introspection is useful if you want to see
+#' the implementation of a specific method.
 #'
 #' @seealso [method_explain()] to explain why a specific method was picked.
 #' @inheritParams method<-
-#' @returns A function with class <S7_method>.
+#' @returns Either a function with class `S7_method` or an error if no
+#'   matching method is found.
 #' @param class,object Perform introspection either with a `class`
 #'   (processed with [as_class()]) or a concrete `object`. If `generic` uses
 #'   multiple dispatch then both `object` and `class` must be a list of

R/method-register.R

@@ -1,4 +1,4 @@
-#' Register a S7 method for a generic
+#' Register an S7 method for a generic
 #'
 #' @description
 #' A generic defines the interface of a function. Once you have created a

R/special.R

@@ -1,20 +1,19 @@
-#' Special dispatch types
+#' Dispatch on a missing argument
 #'
-#' * Use `class_missing` when the user has not supplied an argument
-#' * Use `class_any` for a default method that is called only if no other
-#'   methods are matched
+#' Use `class_missing` to dispatch when the user has not supplied an argument,
+#' i.e. it's missing in the sense of [missing()], not in the sense of
+#' [is.na()].
 #'
 #' @export
 #' @return Sentinel objects used for special types of dispatch.
+#' @format NULL
 #' @examples
 #' foo <- new_generic("foo", "x")
-#' method(foo, class_integer) <- function(x) "integer"
-#' method(foo, class_missing) <- function(x) "missing"
+#' method(foo, class_numeric) <- function(x) "number"
 #' method(foo, class_any) <- function(x) "fallback"
 #'
 #' foo(1)
 #' foo()
-#' foo("x")
 class_missing <- structure(list(), class = "S7_missing")
 
 is_class_missing <- function(x) inherits(x, "S7_missing")
@@ -30,8 +29,20 @@ str.S7_missing <- function(object, ..., nest.lev = 0) {
   print(object)
 }
 
+#' Dispatch on any class
+#'
+#' Use `class_any` to register a default method that is called when no other
+#' methods are matched.
+#'
 #' @export
-#' @rdname class_missing
+#' @format NULL
+#' @examples
+#' foo <- new_generic("foo", "x")
+#' method(foo, class_numeric) <- function(x) "number"
+#' method(foo, class_any) <- function(x) "fallback"
+#'
+#' foo(1)
+#' foo("x")
 class_any <- structure(list(), class = "S7_any")
 
 is_class_any <- function(x) inherits(x, "S7_any")

_pkgdown.yml

@@ -24,17 +24,30 @@ reference:
 - title: Method dispatch
   contents:
   - convert
-  - super
-  - as_class
+  - class_missing
+  - class_any
   - method
   - method_explain
+  - super
+  - S7_class
+
+- title: Packages
+  desc: >
+    Functions needed when using S7 within a package. See `vignette("packages")`
+    for more details.
+  contents:
   - methods_register
   - new_external_generic
+
+- title: Compatibility
+  desc: >
+    These tools provide a layer of compatibility between S7 and S3 classes, S4
+    classes, and base types. See `vignette("compatibility")` for more details.
+  contents:
+  - base_classes
+  - base_s3_classes
   - new_S3_class
   - S4_register
-  - S7_class
-  - base_classes
-  - class_missing
 
 articles:
 - title: Learn S7