Doc tweaks for vector functions

Author: hadley

R/stat-summary.r

@@ -170,17 +170,29 @@ summarise_by_x <- function(data, summary, ...) {
   merge(summary, unique, by = c("x", "group"), sort = FALSE)
 }
 
-#' Wrap up a selection of summary functions from Hmisc to make it easy to use
-#' with \code{\link{stat_summary}}.
-#'
-#' See the Hmisc documentation for details of their options.
-#'
+#' A selection of summary functions from Hmisc
+#'
+#' @description
+#' These are wrappers around functions from \pkg{Hmsic} designed to make them
+#' easier to use with \code{\link{stat_summary}}. See the Hmisc documentation
+#' for more details:
+#'
+#' \itemize{
+#'  \item \code{\link[Hmisc]{smean.cl.boot}}
+#'  \item \code{\link[Hmisc]{smean.cl.normal}}
+#'  \item \code{\link[Hmisc]{smean.sdl}}
+#'  \item \code{\link[Hmisc]{smedian.hilow}}
+#' }
 #' @param x a numeric vector
 #' @param ... other arguments passed on to the respective Hmisc function.
-#' @seealso \code{\link[Hmisc]{smean.cl.boot}},
-#'   \code{\link[Hmisc]{smean.cl.normal}}, \code{\link[Hmisc]{smean.sdl}},
-#'    \code{\link[Hmisc]{smedian.hilow}}
+#' @return A data frame with columns \code{y}, \code{ymin}, and \code{ymax}.
 #' @name hmisc
+#' @examples
+#' x <- rnorm(100)
+#' mean_cl_boot(x)
+#' mean_cl_normal(x)
+#' mean_sdl(x)
+#' median_hilow(x)
 NULL
 
 wrap_hmisc <- function(fun) {
@@ -212,12 +224,17 @@ mean_sdl <- wrap_hmisc("smean.sdl")
 #' @rdname hmisc
 median_hilow <- wrap_hmisc("smedian.hilow")
 
-#' Calculate mean and standard errors on either side.
+#' Calculate mean and standard error
+#'
+#' For use with \code{\link{stat_summary}}
 #'
 #' @param x numeric vector
 #' @param mult number of multiples of standard error
-#' @seealso for use with \code{\link{stat_summary}}
+#' @return A data frame with columns \code{y}, \code{ymin}, and \code{ymax}.
 #' @export
+#' @examples
+#' x <- rnorm(100)
+#' mean_se(x)
 mean_se <- function(x, mult = 1) {
   x <- stats::na.omit(x)
   se <- mult * sqrt(stats::var(x) / length(x))

R/utilities-break.r

@@ -1,4 +1,4 @@
-#' Cut up numeric vector into useful groups.
+#' Discretise numeric data into categorical
 #'
 #' \code{cut_interval} makes \code{n} groups with equal range, \code{cut_number}
 #' makes \code{n} groups with (approximately) equal numbers of observations;

R/utilities-resolution.r

@@ -1,11 +1,9 @@
-#' Compute the "resolution" of a data vector.
+#' Compute the "resolution" of a numeric vector
 #'
 #' The resolution is the smallest non-zero distance between adjacent
 #' values.  If there is only one unique value, then the resolution is defined
-#' to be one.
-#'
-#' If x is an integer vector, then it is assumed to represent a discrete
-#' variable, and the resolution is 1.
+#' to be one. If x is an integer vector, then it is assumed to represent a
+#' discrete variable, and the resolution is 1.
 #'
 #' @param x numeric vector
 #' @param zero should a zero value be automatically included in the
@@ -15,8 +13,10 @@
 #' resolution(1:10)
 #' resolution((1:10) - 0.5)
 #' resolution((1:10) - 0.5, FALSE)
-#' resolution(c(1,2, 10, 20, 50))
-#' resolution(as.integer(c(1, 10, 20, 50)))  # Returns 1
+#'
+#' # Note the difference between numeric and integer vectors
+#' resolution(c(2, 10, 20, 50))
+#' resolution(c(2L, 10L, 20L, 50L))
 resolution <- function(x, zero = TRUE) {
   if (is.integer(x) || zero_range(range(x, na.rm = TRUE)))
     return(1)

_pkgdown.yml

@@ -157,6 +157,9 @@ reference:
   - print.ggproto
 
 - title: Vector helpers
+  desc: >
+    ggplot2 also provides a handful of helpers that are useful for creating
+    visualisations.
   contents:
   - cut_interval
   - hmisc