Doc tweaks for facets

Author: hadley

R/facet-grid-.r

@@ -1,7 +1,11 @@
 #' @include facet-.r
 NULL
 
-#' Lay out panels in a grid.
+#' Lay out panels in a grid
+#'
+#' \code{facet_grid} forms a matrix of panels defined by row and column
+#' facetting variables. It is most useful when you have two discrete
+#' variables, and all combinations of the variables exist in the data.
 #'
 #' @param facets a formula with the rows (of the tabular display) on the LHS
 #'   and the columns (of the tabular display) on the RHS; the dot in the

R/facet-null.r

@@ -4,6 +4,7 @@ NULL
 #' Facet specification: a single panel.
 #'
 #' @inheritParams facet_grid
+#' @keywords internal
 #' @export
 #' @examples
 #' # facet_null is the default facetting specification if you

R/facet-wrap.r

@@ -1,12 +1,11 @@
 #' @include facet-.r
 NULL
 
-#' Wrap a 1d ribbon of panels into 2d.
+#' Wrap a 1d ribbon of panels into 2d
 #'
-#' Most displays are roughly rectangular, so if you have a categorical
-#' variable with many levels, it doesn't make sense to try and display them
-#' all in one row (or one column). To solve this dilemma, \code{facet_wrap}
-#' wraps a 1d sequence of panels into 2d, making best use of screen real estate.
+#' \code{facet_wrap} wraps a 1d sequence of panels into 2d. This is generally
+#' a better use of screen space than \code{\link{facet_grid}} because most
+#' displays are roughly rectangular.
 #'
 #' @param facets Either a formula or character vector. Use either a
 #'   one sided formula, \code{~a + b}, or a character vector, \code{c("a", "b")}.

R/labeller.r

@@ -1,4 +1,4 @@
-#' Labeller functions
+#' Useful labeller functions
 #'
 #' Labeller functions are in charge of formatting the strip labels of
 #' facet grids and wraps. Most of them accept a \code{multi_line}
@@ -65,7 +65,6 @@
 #' @family facet
 #' @seealso \code{\link{labeller}()}, \code{\link{as_labeller}()},
 #'   \code{\link{label_bquote}()}
-#' @name labellers
 #' @examples
 #' mtcars$cyl2 <- factor(mtcars$cyl, labels = c("alpha", "beta", "gamma"))
 #' p <- ggplot(mtcars, aes(wt, mpg)) + geom_point()
@@ -87,6 +86,8 @@
 #' p + facet_grid(. ~ cyl2, labeller = label_parsed)
 #' p + facet_wrap(~vs + cyl2, labeller = label_parsed)
 #' }
+#' @name labellers
+#' @aliases NULL
 NULL
 
 collapse_labels_lines <- function(labels) {
@@ -178,11 +179,12 @@ find_names <- function(expr) {
   }
 }
 
-#' Backquoted labeller
+#' Label with mathematical expressions
 #'
-#' \code{\link{label_bquote}()} offers a flexible way of labelling
+#' \code{label_bquote()} offers a flexible way of labelling
 #' facet rows or columns with plotmath expressions. Backquoted
 #' variables will be replaced with their value in the facet.
+#'
 #' @param rows Backquoted labelling expression for rows.
 #' @param cols Backquoted labelling expression for columns.
 #' @param default Default labeller function for the rows or the
@@ -281,6 +283,7 @@ resolve_labeller <- function(rows, cols, labels) {
 #' @param default Default labeller to process the labels produced by
 #'   lookup tables or modified by non-labeller functions.
 #' @seealso \code{\link{labeller}()}, \link{labellers}
+#' @keywords internal
 #' @export
 #' @examples
 #' p <- ggplot(mtcars, aes(disp, drat)) + geom_point()
@@ -322,7 +325,7 @@ as_labeller <- function(x, default = label_value, multi_line = TRUE) {
   structure(fun, class = "labeller")
 }
 
-#' Generic labeller function for facets
+#' Construct labelling specification
 #'
 #' This function makes it easy to assign different labellers to
 #' different factors. The labeller can be a function or it can be a

_pkgdown.yml

@@ -64,11 +64,22 @@ reference:
   - starts_with("scale_")
 
 - title: Facetting
+  desc: >
+    Facetting generates small multiples, each displaying a different
+    subset of the data. Facets are an alternative to aesthetics for
+    displaying additional discrete variables.
+  contents:
+  - facet_grid
+  - facet_wrap
+
+- title: "Facetting: labels"
+  desc: >
+    These functions provide a flexible toolkit for controlling the display
+    of the "strip" labels on facets.
   contents:
-  - starts_with("facet_")
   - labeller
   - labellers
-  - as_labeller
+  - label_value
   - label_bquote
 
 - title: Coordinate systems