Guide doc tweaks

Author: hadley

R/axis-secondary.R

@@ -1,7 +1,8 @@
-#' Secondary axes
+#' Specify a secondary axis
 #'
-#' Create a secondary axis as a transformation of the primary axis, positioned
-#' opposite of the primary axis.
+#' This function is used in conjunction with a position scale to create a
+#' secondary axis, positioned opposite of the primary axis. All secondary
+#' axes must be based on a one-to-one transformation of the primary axes.
 #'
 #' @param trans A transformation formula
 #'

R/guide-legend.r

@@ -1,4 +1,4 @@
-#' Legend guide.
+#' Legend guide
 #'
 #' Legend type guide shows key (i.e., geoms) mapped onto values.
 #' Legend guides for various scales are integrated if possible.

R/guides-.r

@@ -1,9 +1,12 @@
-#' Set guides for each scale.
+#' Set guides for each scale
 #'
-#' Guides for each scale can be set in call of \code{scale_*} with argument
-#' \code{guide}, or in \code{guides}.
+#' Guides for each scale can be set scale-by-scale with the \code{guide}
+#' argument, or en masse with \code{guides()}.
 #'
-#' @param ... List of scale guide pairs
+#' @param ... List of scale name-guide pairs.  The guide can either
+#'   be a string (i.e. "colorbar" or "legend"), or a call to a guide function
+#'   (i.e. \code{\link{guide_colourbar}} or \code{\link{guide_legend}})
+#'   specifying additional arguments.
 #' @return A list containing the mapping between scale and guide.
 #' @export
 #' @family guides

_pkgdown.yml

@@ -61,8 +61,22 @@ reference:
   contents:
   - labs
   - lims
+  - expand_limits
   - starts_with("scale_")
 
+- title: "Guides: axes and legends"
+  desc: >
+    The guides (the axes and legends) help readers interpret your plots.
+    Guides are mostly controlled via the scale (e.g. with the `limits`,
+    `breaks`, and `labels` arguments), but sometimes you will need additional
+    cover over the guide apperance. Use `guides()` or the `guide` argument to
+    individual scales along with `guide_colourbar()` or `guide_legend()`.
+  contents:
+  - guide_colourbar
+  - guide_legend
+  - guides
+  - sec_axis
+
 - title: Facetting
   desc: >
     Facetting generates small multiples, each displaying a different
@@ -94,18 +108,6 @@ reference:
   - annotation_map
   - annotation_raster
 
-- title: "Guides: axes and legends"
-  desc: >
-    The guides (the axes and legends) help readers interpret your plots.
-    The guide functions give deep control over the details of the apperance.
-    Override with using `guides()` or the `guide` argument to individual scales.
-  contents:
-  - guide_colourbar
-  - guide_legend
-  - guides
-  - expand_limits
-  - sec_axis
-
 - title: Themes
   contents:
   - ggtheme
@@ -121,7 +123,7 @@ reference:
   - aes_
   - print.ggplot
 
-- title: ggproto
+- title: Extending ggplot2 with ggproto
   contents:
   - ggproto
   - as.list.ggproto
@@ -152,7 +154,6 @@ reference:
   - aes_linetype_size_shape
   - aes_position
   - borders
-  - ggplot2-package
   - graphical-units
   - last_plot
   - map_data