Doc tweaks for annotations + general reorg

Author: hadley

R/annotation-custom.r

@@ -1,12 +1,13 @@
 #' @include geom-.r
 NULL
 
-#' Annotation: Custom grob.
+#' Annotation: Custom grob
 #'
 #' This is a special geom intended for use as static annotations
 #' that are the same in every panel. These annotations will not
 #' affect scales (i.e. the x and y axes will not grow to cover the range
-#' of the grob, and the grob will not be modified by any ggplot settings or mappings).
+#' of the grob, and the grob will not be modified by any ggplot settings
+#' or mappings).
 #'
 #' Most useful for adding tables, inset plots, and other grid-based decorations.
 #'

R/annotation-map.r

@@ -1,7 +1,9 @@
 #' @include geom-map.r
 NULL
 
-#' Annotation: maps.
+#' Annotation: a maps
+#'
+#' Display a fixed map on a plot.
 #'
 #' @param map data frame representing a map.  Most map objects can be
 #'   converted into the right format by using \code{\link{fortify}}

R/annotation-raster.r

@@ -2,14 +2,13 @@
 #' @include geom-raster.r
 NULL
 
-#' Annotation: High-performance rectangular tiling.
+#' Annotation: high-performance rectangular tiling
 #'
 #' This is a special version of \code{\link{geom_raster}} optimised for static
 #' annotations that are the same in every panel. These annotations will not
 #' affect scales (i.e. the x and y axes will not grow to cover the range
-#' of the raster, and the raster must already have its own colours).
-#'
-#' Most useful for adding bitmap images.
+#' of the raster, and the raster must already have its own colours). This
+#' is useful for adding bitmap images.
 #'
 #' @param raster raster object to display
 #' @param xmin,xmax x location (in data coordinates) giving horizontal

R/annotation.r

@@ -1,6 +1,6 @@
-#' Create an annotation layer.
+#' Create an annotation layer
 #'
-#' This function adds geoms to a plot. Unlike typical a geom function,
+#' This function adds geoms to a plot, but unlike typical a geom function,
 #' the properties of the geoms are not mapped from variables of a data frame,
 #' but are instead passed in as vectors. This is useful for adding small annotations
 #' (such as text labels) or if you have your data in vectors, and for some

R/fortify-map.r

@@ -68,7 +68,12 @@ map_data <- function(map, region = ".", exact = FALSE, ...) {
   fortify(map(map, region, exact = exact, plot = FALSE, fill = TRUE, ...))
 }
 
-#' Create a layer of map borders.
+#' Create a layer of map borders
+#'
+#' This is a quick and dirty way to get map data (from the maps package)
+#' on to your plot. This is a good place to start if you need some crude
+#' reference lines, but you'll typically want something more sophisticated
+#' for communication graphics.
 #'
 #' @param database map data, see \code{\link[maps]{map}} for details
 #' @param regions map region

R/plot-last.r

@@ -16,4 +16,5 @@ set_last_plot <- function(value) .store$set(value)
 #'
 #' @seealso \code{\link{ggsave}}
 #' @export
+#' @keywords internal
 last_plot <- function() .store$get()

_pkgdown.yml

@@ -51,6 +51,19 @@ reference:
   contents:
   - starts_with("position_")
 
+- title: "Layer: annotations"
+  desc: >
+    Annotation are special types of layer than don't inherit global settings
+    from the plot. Rhey are used to add fixed reference data to plot.
+  contents:
+  - geom_abline
+  - annotate
+  - annotation_custom
+  - annotation_logticks
+  - annotation_map
+  - annotation_raster
+  - borders
+
 - title: Scales
   desc: >
     Scales control the details of how data values are translated to visual
@@ -100,14 +113,6 @@ reference:
   contents:
   - starts_with("coord_")
 
-- title: Annotations
-  contents:
-  - annotate
-  - annotation_custom
-  - annotation_logticks
-  - annotation_map
-  - annotation_raster
-
 - title: Themes
   contents:
   - ggtheme
@@ -117,6 +122,8 @@ reference:
   - rel
   - is.rel
   - is.theme
+  - margin
+  - graphical-units
 
 - title: Programming with ggplot2
   contents:
@@ -139,12 +146,14 @@ reference:
   - fortify.map
   - fortify
   - fortify.sp
+  - map_data
 
 - title: Vector helpers
   contents:
   - cut_interval
   - hmisc
   - mean_se
+  - resolution
 
 - title: All functions
   desc: ~
@@ -153,12 +162,6 @@ reference:
   - aes_group_order
   - aes_linetype_size_shape
   - aes_position
-  - borders
-  - graphical-units
-  - last_plot
-  - map_data
-  - margin
-  - resolution
   - translate_qplot_ggplot
   - translate_qplot_lattice
   - qplot