Doc tweaks for programming/extending

Author: hadley

R/aes.r

@@ -103,24 +103,25 @@ is_position_aes <- function(vars) {
   aes_to_scale(vars) %in% c("x", "y")
 }
 
-#' Define aesthetic mappings from strings, or quoted calls and formulas.
+#' Define aesthetic mappings programatically
 #'
 #' Aesthetic mappings describe how variables in the data are mapped to visual
 #' properties (aesthetics) of geoms. \code{\link{aes}} uses non-standard
 #' evaluation to capture the variable names. \code{aes_} and \code{aes_string}
 #' require you to explicitly quote the inputs either with \code{""} for
 #' \code{aes_string()}, or with \code{quote} or \code{~} for \code{aes_()}.
-#' (\code{aes_q} is an alias to \code{aes_})
-#'
-#' It's better to use \code{aes_q()}, because there's no easy way to create the
-#' equivalent to \code{aes(colour = "my colour")} or \code{aes{x = `X$1`}}
-#' with \code{aes_string()}.
+#' (\code{aes_q} is an alias to \code{aes_}). This makes \code{aes_} and
+#' \code{aes_string} easy to program with.
 #'
 #' \code{aes_string} and \code{aes_} are particularly useful when writing
 #' functions that create plots because you can use strings or quoted
 #' names/calls to define the aesthetic mappings, rather than having to use
 #' \code{\link{substitute}} to generate a call to \code{aes()}.
 #'
+#' I recommend using \code{aes_()}, because creating the equivalents of
+#' \code{aes(colour = "my colour")} or \code{aes{x = `X$1`}}
+#' with \code{aes_string()} is quite clunky.
+#'
 #' @param x,y,... List of name value pairs. Elements must be either
 #'   quoted calls, strings, one-sided formulas or constants.
 #' @seealso \code{\link{aes}}

R/ggproto.r

@@ -1,11 +1,18 @@
 #' Create a new ggproto object
 #'
-#' ggproto is inspired by the proto package, but it has some important
-#' differences. Notably, it cleanly supports cross-package inheritance, and has
-#' faster performance.
+#' Construct a new object with \code{ggproto}, test with \code{is.proto},
+#' and access parent methods/fields with \code{ggproto_parent}.
 #'
-#' @section Calling ggproto methods:
+#' ggproto implements a protype based OO system which blurs the lines between
+#' classes and instances. It is inspired by the proto package, but it has some
+#' important differences. Notably, it cleanly supports cross-package
+#' inheritance, and has faster performance.
 #'
+#' In most cases, creating a new OO system to be used by a single package is
+#' not a good idea. However, it was the least-bad solution for ggplot2 because
+#' it required the fewest changes to an already complex code base.
+#'
+#' @section Calling methods:
 #' ggproto methods can take an optional \code{self} argument: if it is present,
 #' it is a regular method; if it's absent, it's a "static" method (i.e. it
 #' doesn't use any fields).
@@ -17,18 +24,36 @@
 #' in the function signature, although customarily it comes first.
 #'
 #' @section Calling methods in a parent:
-#'
 #' To explicitly call a methods in a parent, use
 #' \code{ggproto_parent(Parent, self)}.
 #'
 #' @param _class Class name to assign to the object. This is stored as the class
-#'   attribute of the object. If \code{NULL} (the default), no class name will
-#'   be added to the object.
-#' @param _inherit ggproto object to inherit from. If \code{NULL}, don't inherit
-#'   from any object.
-#' @param parent,self Access parent class \code{parent} of object \code{self}.
+#'   attribute of the object. This is optional: if \code{NULL} (the default),
+#'   no class name will be added to the object.
+#' @param _inherit ggproto object to inherit from. If \code{NULL}, don't
+#'   inherit from any object.
 #' @param ... A list of members in the ggproto object.
 #' @export
+#' @examples
+#' Adder <- ggproto("Adder",
+#'   x = 0,
+#'   add = function(self, n) {
+#'     self$x <- self$x + n
+#'     self$x
+#'   }
+#'  )
+#' is.ggproto(Adder)
+#'
+#' Adder$add(10)
+#' Adder$add(10)
+#'
+#' Doubler <- ggproto("Doubler", Adder,
+#'   add = function(self, n) {
+#'     ggproto_parent(Adder, self)$add(n * 2)
+#'   }
+#' )
+#' Doubler$x
+#' Doubler$add(10)
 ggproto <- function(`_class` = NULL, `_inherit` = NULL, ...) {
   e <- new.env(parent = emptyenv())
 
@@ -65,10 +90,17 @@ ggproto <- function(`_class` = NULL, `_inherit` = NULL, ...) {
   e
 }
 
-#' Is an object a ggproto object?
-#'
+
+#' @export
+#' @rdname ggproto
+#' @param parent,self Access parent class \code{parent} of object \code{self}.
+ggproto_parent <- function(parent, self) {
+  structure(list(parent = parent, self = self), class = "ggproto_parent")
+}
+
 #' @param x An object to test.
 #' @export
+#' @rdname ggproto
 is.ggproto <- function(x) inherits(x, "ggproto")
 
 fetch_ggproto <- function(x, name) {
@@ -98,12 +130,6 @@ fetch_ggproto <- function(x, name) {
   res
 }
 
-#' @export
-#' @rdname ggproto
-ggproto_parent <- function(parent, self) {
-  structure(list(parent = parent, self = self), class = "ggproto_parent")
-}
-
 #' @export
 `$.ggproto` <- function(x, name) {
   res <- fetch_ggproto(x, name)
@@ -140,7 +166,6 @@ make_proto_method <- function(self, f) {
   fun
 }
 
-
 #' @export
 `[[.ggproto` <- `$.ggproto`
 
@@ -153,6 +178,7 @@ make_proto_method <- function(self, f) {
 #'   the returned list. If \code{FALSE}, do not include any inherited items.
 #' @param ... Further arguments to pass to \code{as.list.environment}.
 #' @export
+#' @keywords internal
 as.list.ggproto <- function(x, inherit = TRUE, ...) {
   res <- list()
 
@@ -169,7 +195,7 @@ as.list.ggproto <- function(x, inherit = TRUE, ...) {
 }
 
 
-#' Print a ggproto object
+#' Format or print a ggproto object
 #'
 #' If a ggproto object has a \code{$print} method, this will call that method.
 #' Otherwise, it will print out the members of the object, and optionally, the
@@ -182,6 +208,14 @@ as.list.ggproto <- function(x, inherit = TRUE, ...) {
 #'   will be passed to it. Otherwise, these arguments are unused.
 #'
 #' @export
+#' @examples
+#' Dog <- ggproto(
+#'   print = function(self, n) {
+#'     cat("Woof!\n")
+#'   }
+#'  )
+#' Dog
+#' cat(format(Dog), "\n")
 print.ggproto <- function(x, ..., flat = TRUE) {
   if (is.function(x$print)) {
     x$print(...)
@@ -193,10 +227,8 @@ print.ggproto <- function(x, ..., flat = TRUE) {
 }
 
 
-#' Format a ggproto object
-#'
-#' @inheritParams print.ggproto
 #' @export
+#' @rdname print.ggproto
 format.ggproto <-  function(x, ..., flat = TRUE) {
   classes_str <- function(obj) {
     classes <- setdiff(class(obj), "ggproto")

R/plot.r

@@ -121,7 +121,12 @@ plot_clone <- function(plot) {
 #' @export
 is.ggplot <- function(x) inherits(x, "ggplot")
 
-#' Draw plot on current graphics device.
+#' Explicitly draw plot
+#'
+#' Generally, you do not need to print or plot a ggplot2 plot explicitly: the
+#' default top-level print method will do it for you. You will, however, need
+#' to call \code{print()} explicitly if you want to draw a plot inside a
+#' function or for loop.
 #'
 #' @param x plot to display
 #' @param newpage draw new (empty) page first?
@@ -133,6 +138,20 @@ is.ggplot <- function(x) inherits(x, "ggplot")
 #'   information about the scales, panels etc.
 #' @export
 #' @method print ggplot
+#' @examples
+#' colours <- list(~class, ~drv, ~fl)
+#'
+#' # Doesn't seem to do anything!
+#' for (colour in colours) {
+#'   ggplot(mpg, aes_(~ displ, ~ hwy, colour = colour)) +
+#'     geom_point()
+#' }
+#'
+#' # Works when we explicitly print the plots
+#' for (colour in colours) {
+#'   print(ggplot(mpg, aes_(~ displ, ~ hwy, colour = colour)) +
+#'     geom_point())
+#' }
 print.ggplot <- function(x, newpage = is.null(vp), vp = NULL, ...) {
   set_last_plot(x)
   if (newpage) grid.newpage()

_pkgdown.yml

@@ -139,16 +139,21 @@ reference:
   - margin
 
 - title: Programming with ggplot2
+  desc: >
+    These functions provides tools to help you program with ggplot2,
+    creating functions and for-loops that generate plots for you.
   contents:
   - aes_
   - print.ggplot
 
 - title: Extending ggplot2 with ggproto
+  desc: >
+    To create your own geoms, stats, scales, and facets, you'll need to learn
+    a bit about the object oriented system that ggplot2 uses. Start by
+    reading `vignette("extending-ggplot2")` then consult these functions
+    for more details.
   contents:
   - ggproto
-  - as.list.ggproto
-  - is.ggproto
-  - format.ggproto
   - print.ggproto
 
 - title: Autoplot and fortify