Tweak docs for plot basics

Author: hadley

R/aes.r

@@ -22,23 +22,21 @@ NULL
   "max"   = "ymax"
 )
 
-#' Define aesthetic mappings.
+#' Construct aesthetic mappings
 #'
-#' Generate aesthetic mappings that describe how variables in the data are
-#' mapped to visual properties (aesthetics) of geoms. This function also
-#' standardise aesthetic names by performs partial name matching, converting
-#' color to colour, and old style R names to ggplot names (eg. pch to shape,
-#' cex to size)
+#' Aesthetic mappings describe how variables in the data are mapped to visual
+#' properties (aesthetics) of geoms. Aesthetic mappings can be set in
+#' \code{\link{ggplot2}} and in individual layers.
+#'
+#' This function also standardise aesthetic names by performing partial
+#' matching, converting color to colour, and translating old style R names to
+#' ggplot names (eg. pch to shape, cex to size)
 #'
 #' @param x,y,... List of name value pairs giving aesthetics to map to
-#'   variables. The names for x and y aesthetics can be omitted (because
-#'   they are so common); all other aesthetics must be named.
-#' @seealso See \code{\link{aes_q}}/\code{\link{aes_string}} for standard
-#'   evaluation versions of \code{aes}.
-#' @seealso See
-#'    \code{\link{aes_colour_fill_alpha}}, \code{\link{aes_group_order}},
-#'    \code{\link{aes_linetype_size_shape}} and \code{\link{aes_position}}
-#'    for more specific examples with different aesthetics.
+#'   variables. The names for x and y aesthetics are typically omitted because
+#'   they are so common; all other aesthetics must be named.
+#' @seealso See \code{\link{aes_}} for a version of \code{aes} that is
+#'   more suitable for programming with.
 #' @export
 #' @examples
 #' aes(x = mpg, y = wt)

R/plot.r

@@ -1,23 +1,20 @@
-#' Create a new ggplot plot.
+#' Create a new ggplot
 #'
 #' \code{ggplot()} initializes a ggplot object. It can be used to
 #' declare the input data frame for a graphic and to specify the
 #' set of plot aesthetics intended to be common throughout all
 #' subsequent layers unless specifically overridden.
 #'
-#' \code{ggplot()} is typically used to construct a plot
-#' incrementally, using the + operator to add layers to the
-#' existing ggplot object. This is advantageous in that the
-#' code is explicit about which layers are added and the order
-#' in which they are added. For complex graphics with multiple
-#' layers, initialization with \code{ggplot} is recommended.
+#' \code{ggplot()} is used to construct the initial plot object,
+#' and is almost always followed by \code{+} to add component to the
+#' plot. There are three common ways to invoke \code{ggplot}:
+#'
+#' \enumerate{
+#'   \item \code{ggplot(df, aes(x, y, <other aesthetics>))}
+#'   \item \code{ggplot(df)}
+#'   \item \code{ggplot()}
+#' }
 #'
-#' There are three common ways to invoke \code{ggplot}:
-#' \itemize{
-#'    \item \code{ggplot(df, aes(x, y, <other aesthetics>))}
-#'    \item \code{ggplot(df)}
-#'    \item \code{ggplot()}
-#'   }
 #' The first method is recommended if all layers use the same
 #' data and the same set of aesthetics, although this method
 #' can also be used to add a layer using data from another
@@ -42,51 +39,52 @@
 #'   to using the environment in which \code{ggplot()} is called.
 #' @export
 #' @examples
-#' df <- data.frame(gp = factor(rep(letters[1:3], each = 10)),
-#'                  y = rnorm(30))
-#' # Compute sample mean and standard deviation in each group
+#' # Generate some sample data, then compute mean and standard deviation
+#' # in each group
+#' df <- data.frame(
+#'   gp = factor(rep(letters[1:3], each = 10)),
+#'   y = rnorm(30)
+#' )
 #' ds <- plyr::ddply(df, "gp", plyr::summarise, mean = mean(y), sd = sd(y))
 #'
-#' # Declare the data frame and common aesthetics.
-#' # The summary data frame ds is used to plot
-#' # larger red points in a second geom_point() layer.
-#' # If the data = argument is not specified, it uses the
-#' # declared data frame from ggplot(); ditto for the aesthetics.
-#' ggplot(df, aes(x = gp, y = y)) +
-#'    geom_point() +
-#'    geom_point(data = ds, aes(y = mean),
-#'               colour = 'red', size = 3)
+#' # The summary data frame ds is used to plot larger red points on top
+#' # of the raw data. Note that we don't need to supply `data` or `mapping`
+#' # in each layer because the defaults from ggplot() are used.
+#' ggplot(df, aes(gp, y)) +
+#'   geom_point() +
+#'   geom_point(data = ds, aes(y = mean), colour = 'red', size = 3)
+#'
 #' # Same plot as above, declaring only the data frame in ggplot().
 #' # Note how the x and y aesthetics must now be declared in
 #' # each geom_point() layer.
 #' ggplot(df) +
-#'    geom_point(aes(x = gp, y = y)) +
-#'    geom_point(data = ds, aes(x = gp, y = mean),
-#'                  colour = 'red', size = 3)
-#' # Set up a skeleton ggplot object and add layers:
+#'   geom_point(aes(gp, y)) +
+#'   geom_point(data = ds, aes(gp, mean), colour = 'red', size = 3)
+#'
+#' # Alternatively we can fully specify the plot in each layer. This
+#' # is not useful here, but can be more clear when working with complex
+#' # mult-dataset graphics
 #' ggplot() +
-#'   geom_point(data = df, aes(x = gp, y = y)) +
-#'   geom_point(data = ds, aes(x = gp, y = mean),
-#'                         colour = 'red', size = 3) +
-#'   geom_errorbar(data = ds, aes(x = gp, y = mean,
-#'                     ymin = mean - sd, ymax = mean + sd),
-#'                     colour = 'red', width = 0.4)
+#'   geom_point(data = df, aes(gp, y)) +
+#'   geom_point(data = ds, aes(gp, mean), colour = 'red', size = 3) +
+#'   geom_errorbar(
+#'     data = ds,
+#'     aes(gp, mean, ymin = mean - sd, ymax = mean + sd),
+#'     colour = 'red',
+#'     width = 0.4
+#'   )
 ggplot <- function(data = NULL, mapping = aes(), ...,
                    environment = parent.frame()) {
   UseMethod("ggplot")
 }
 
 #' @export
-#' @rdname ggplot
-#' @usage NULL
 ggplot.default <- function(data = NULL, mapping = aes(), ...,
                            environment = parent.frame()) {
   ggplot.data.frame(fortify(data, ...), mapping, environment = environment)
 }
 
 #' @export
-#' @rdname ggplot
-#' @usage NULL
 ggplot.data.frame <- function(data, mapping = aes(), ...,
                               environment = parent.frame()) {
   if (!missing(mapping) && !inherits(mapping, "uneval")) {

R/save.r

@@ -7,21 +7,18 @@
 #'
 #' @param filename File name to create on disk.
 #' @param plot Plot to save, defaults to last plot displayed.
-#' @param device Device to use (function or any of the recognized extensions,
-#'   e.g. \code{"pdf"}). By default, extracted from filename extension.
-#'   \code{ggsave} currently recognises eps/ps, tex (pictex), pdf, jpeg, tiff,
-#'   png, bmp, svg and wmf (windows only).
+#' @param device Device to use. Can be either be a device function
+#'   (e.g. \code{\link{png}}), or one of "eps", "ps", "tex" (pictex),
+#'   "pdf", "jpeg", "tiff", "png", "bmp", "svg" or "wmf" (windows only).
 #' @param path Path to save plot to (combined with filename).
 #' @param scale Multiplicative scaling factor.
-#' @param width,height Plot dimensions, defaults to size of current graphics
-#'   device.
-#' @param units Units for width and height when specified explicitly (in, cm,
-#'   or mm)
-#' @param dpi Resolution used for raster outputs.
+#' @param width,height,units Plot size in \code{units} ("in", "cm", or "mm").
+#'   If not supplied, uses the size of current graphics device.
+#' @param dpi Plot resolution. Applies only to raster output types.
 #' @param limitsize When \code{TRUE} (the default), \code{ggsave} will not
 #'   save images larger than 50x50 inches, to prevent the common error of
 #'   specifying dimensions in pixels.
-#' @param ... Other arguments passed on to graphics device
+#' @param ... Other arguments passed on to graphics \code{device}.
 #' @export
 #' @examples
 #' \dontrun{