Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation polishing #388

Merged
merged 1 commit into from
Nov 27, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 16 additions & 4 deletions R/S3.R
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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",
Expand All @@ -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",
Expand All @@ -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",
Expand All @@ -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",
Expand Down
18 changes: 5 additions & 13 deletions R/base.R
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand All @@ -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.
Expand Down
1 change: 1 addition & 0 deletions R/class-spec.R
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
15 changes: 8 additions & 7 deletions R/method-introspect.R
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion R/method-register.R
Original file line number Diff line number Diff line change
@@ -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
Expand Down
27 changes: 19 additions & 8 deletions R/special.R
Original file line number Diff line number Diff line change
@@ -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")
Expand All @@ -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")
Expand Down
23 changes: 18 additions & 5 deletions _pkgdown.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions man/as_class.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

33 changes: 6 additions & 27 deletions man/base_classes.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

30 changes: 30 additions & 0 deletions man/base_s3_classes.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

22 changes: 22 additions & 0 deletions man/class_any.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

22 changes: 5 additions & 17 deletions man/class_missing.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion man/method-set.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading
Loading