Improve clarity of docstring for ggplot()

changed "component" to "components"
used "pattern" instead of "way" and "method"
broke each pattern description in to separate paragraph
used more explicit names in example code
added more explicit comments in example code
removed error bars in last pattern of example code (and removed standard deviations from the summary stats calculated)

Author: kevinxperese

R/plot.r

@@ -6,23 +6,26 @@
 #' subsequent layers unless specifically overridden.
 #'
 #' `ggplot()` is used to construct the initial plot object,
-#' and is almost always followed by `+` to add component to the
-#' plot. There are three common ways to invoke `ggplot()`:
+#' and is almost always followed by a plus sign (`+`) to add
+#' components to the plot.
+#' There are three common patterns used to invoke `ggplot()`:
 #'
 #' * `ggplot(df, aes(x, y, other aesthetics))`
 #' * `ggplot(df)`
 #' * `ggplot()`
 #'
-#' The first method is recommended if all layers use the same
+#' The first pattern 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
-#' data frame. See the first example below. The second
-#' method specifies the default data frame to use for the plot,
-#' but no aesthetics are defined up front. This is useful when
-#' one data frame is used predominantly as layers are added,
-#' but the aesthetics may vary from one layer to another. The
-#' third method initializes a skeleton `ggplot` object which
-#' is fleshed out as layers are added. This method is useful when
+#' can also be used when adding a layer using data from another
+#' data frame. 
+#'
+#' The second pattern specifies the default data frame to use
+#' for the plot, but no aesthetics are defined up front. This
+#' is useful when one data frame is used predominantly for the
+#' plot, but the aesthetics may vary from one layer to another. 
+#'
+#' The third pattern initializes a skeleton `ggplot` object, which
+#' is fleshed out as layers are added. This is useful when
 #' multiple data frames are used to produce different layers, as
 #' is often the case in complex graphics.
 #'
@@ -36,43 +39,41 @@
 #'   evaluation.
 #' @export
 #' @examples
-#' # Generate some sample data, then compute mean and standard deviation
-#' # in each group
+#' # Create a data frame with some sample data, then create a data frame
+#' # containing the mean for each group in the sample data.
 #' set.seed(1)
-#' df <- data.frame(
-#'   gp = factor(rep(letters[1:3], each = 10)),
-#'   y = rnorm(30)
+#' sample_df <- data.frame(
+#'   group = factor(rep(letters[1:3], each = 10)),
+#'   value = rnorm(30)
 #' )
-#' ds <- do.call(rbind, lapply(split(df, df$gp), function(d) {
-#'   data.frame(mean = mean(d$y), sd = sd(d$y), gp = d$gp)
+#' group_means_df <- do.call(rbind, lapply(split(sample_df, sample_df$group), function(d) {
+#'   data.frame(group_mean = mean(d$value), group = d$group)
 #' }))
-#'
-#' # 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)) +
+#' 
+#' # Pattern 1
+#' # The group means data frame is used to plot larger red points on top
+#' # of the sample data. Note that we don't need to supply `data =` or `mapping =`
+#' # in each layer because the arguments are passed into ggplot() in the default
+#' # positions.
+#' ggplot(sample_df, aes(x = group, y = value)) +
 #'   geom_point() +
-#'   geom_point(data = ds, aes(y = mean), colour = 'red', size = 3)
-#'
+#'   geom_point(group_means_df, aes(y = group_mean), colour = 'red', size = 3)
+#' 
+#' # Pattern 2
 #' # 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(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(sample_df) +
+#'   geom_point(aes(x = group, y = value)) +
+#'   geom_point(group_means_df, aes(x = group, y = group_mean), colour = 'red', size = 3)
+#' 
+#' # Pattern 3
+#' # Alternatively, we can fully specify the plot in each layer. This
+#' # can be particularly useful when working with complex, multi-dataset graphics.
 #' ggplot() +
-#'   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
-#'   )
+#'  geom_point(sample_df, aes(x = group, y = value)) +
+#'  geom_point(group_means_df, aes(x = group, y = group_mean), colour = 'red', size = 3)
+#' }
 ggplot <- function(data = NULL, mapping = aes(), ...,
                    environment = parent.frame()) {
   UseMethod("ggplot")