export & write documentation

Author: teunbrand

R/all-classes.R

@@ -1,26 +1,165 @@
-# S3 classes --------------------------------------------------------------
+# Docs -------------------------------------------------------------
 
-# Meta classes:
-# TODO: These should be replaced once R 4.3.0 is the minimum version as `+`
-# dispatch should work as intended.
-class_gg    <- S7::new_class("gg", abstract = TRUE)
-class_S3_gg <- S7::new_S3_class("gg")
+#' Class definitions
+#'
+#' The S7 object oriented programming system requires class definitions.
+#' Here, we provide definitions of classes that are home to ggplot2.
+#'
+#' @section S7 classes:
+#'
+#' A general advice the S7 package gives is to name class definition objects
+#' the same as the class name, which then becomes the constructor for the class.
+#' The classes listed below deviate from that advice for historical reasons,
+#' because some constructors like `ggplot()` are also S3 generics with methods.
+#' The have the `class_`-prefix to indicate their role.
+#'
+#' * [`class_ggplot`] is an S7 class used for objects generated by [ggplot()].
+#' * [`class_ggplot_built`] is an S7 class used for objects generated by
+#'   [ggplot_build()].
+#' * [`class_mapping`] is an S7 class used for objects generated by [aes()].
+#' * [`class_theme`] is an S7 class used for objects generated by [theme()].
+#' * [`class_labels`] is an S7 class used for objects generated by [labs()].
+#'
+#' @section Theme elements:
+#'
+#' The theme elements follow the advice of the S7 package that the class names
+#' are also the class definitions and constructors.
+#'
+#' * [`element`] is an abstract S7 class used to invoke similar behaviour among
+#'   theme element objects.
+#' * [`element_blank`] is an S7 class for not drawing theme elements.
+#' * [`element_rect`] is an S7 class for drawing rectangles.
+#' * [`element_line`] is an S7 class for drawing lines.
+#' * [`element_text`] is an S7 class for rendering text.
+#' * [`element_polygon`] is an S7 class for drawing polygons.
+#' * [`element_point`] is an S7 class for drawing points.
+#' * [`element_geom`] is an S7 class holding geom defaults.
+#' * [`margin`] is an S7 class for declaring margins.
+#'
+#' @section ggproto classes:
+#'
+#' The ggproto classes are S3 classes of the type environment that form the
+#' backbone of most systems in ggplot2 and are in particular crucial to the
+#' extension system.
+#'
+#' @section S3 classes:
+#'
+#' Some simple classes remain S3.
+#'
+#' @name class_definitions
+NULL
+
+#' @rdname class_definitions
+#' @section S7 classes:
+#' * `class_gg` is an abstract S7 class to used invoke similar behaviour among
+#'   ggplot objects.
+#' @export
+#' @format NULL
+#' @usage NULL
+class_gg <- S7::new_class("gg", abstract = TRUE)
+
+# ggproto classes ---------------------------------------------------------
 
-# Proper S3 classes we need awareness for
+#' @rdname class_definitions
+#' @section ggproto classes:
+#' * `class_ggproto` is an S3 class used for the objects generated by
+#'   [ggproto()] which are of the type environment.
+#' @export
+#' @format NULL
+#' @usage NULL
 class_ggproto <- S7::new_S3_class("ggproto")
-class_gtable  <- S7::new_S3_class("gtable")
 
-# The important ggproto classes that we treat as S3 classes in S7 even though
-# they are their own thing.
-class_scale  <- S7::new_S3_class("Scale")
+# We don't own this class, so we don't export or describe it
+class_gtable <- S7::new_S3_class("gtable")
+
+#' @rdname class_definitions
+#' @section ggproto classes:
+#' * `class_scale` is a subclass of `class_ggproto` and is more described in
+#'   the [Scale] documentation.
+#' @export
+#' @format NULL
+#' @usage NULL
+class_scale <- S7::new_S3_class("Scale")
+
+#' @rdname class_definitions
+#' @section ggproto classes:
+#' * `class_guides` is a subclass of `class_ggproto` and is considered an
+#'   internal class.
+#' @export
+#' @format NULL
+#' @usage NULL
 class_guides <- S7::new_S3_class("Guides")
+
+#' @rdname class_definitions
+#' @section ggproto classes:
+#' * `class_guide` is a subclass of `class_ggproto` and is more described in the
+#'   [Guide] documentation.
+#' @export
+#' @format NULL
+#' @usage NULL
 class_guide  <- S7::new_S3_class("Guide")
+
+#' @rdname class_definitions
+#' @section ggproto classes:
+#' * `class_coord` is a subclass of `class_ggproto` and is more described in the
+#'   [Coord] documentation.
+#' @export
+#' @format NULL
+#' @usage NULL
 class_coord  <- S7::new_S3_class("Coord")
+
+
+#' @rdname class_definitions
+#' @section ggproto classes:
+#' * `class_facet` is a subclass of `class_ggproto` and is more described in the
+#'   [Facet] documentation.
+#' @export
+#' @format NULL
+#' @usage NULL
 class_facet  <- S7::new_S3_class("Facet")
+
+#' @rdname class_definitions
+#' @section ggproto classes:
+#' * `class_layer` is a subclass of `class_ggproto` and is used for the objects
+#'   generated by [layer()]. The class itself is considered internal and is
+#'   described in more detail in the [Layer] documentation.
+#' @export
+#' @format NULL
+#' @usage NULL
 class_layer  <- S7::new_S3_class("Layer")
+
+#' @rdname class_definitions
+#' @section ggproto classes:
+#' * `class_layout` is a subclass of `class_ggproto` and is considered an
+#'   internal class. It is described in more detail in the [Layout]
+#'   documentation.
+#' @export
+#' @format NULL
+#' @usage NULL
 class_layout <- S7::new_S3_class("Layout")
+
+#' @rdname class_definitions
+#' @section ggproto classes:
+#' * `class_scales_list` is a subclass of `class_ggproto` and is considered an
+#'   internal class.
+#' @export
+#' @format NULL
+#' @usage NULL
 class_scales_list <- S7::new_S3_class("ScalesList")
 
+# S3 classes --------------------------------------------------------------
+
+#' @rdname class_definitions
+#' @section S3 classes:
+#' * `r lifecycle::badge("superseded")` `class_S3_gg` is a temporary S3 class
+#'   until R 4.3.0 is the minimum  supported version. It is exported and
+#'   listed here for completeness, but its use is heavily discouraged. It
+#'   is superseded by `class_gg`.
+#' @export
+#' @format NULL
+#' @usage NULL
+class_S3_gg <- S7::new_S3_class("gg")
+
 # User facing classes -----------------------------------------------------
 
 ## Theme -------------------------------------------------------------------