added roxygen bits and adhered to coding style standards

Author: hrbrmstr

NEWS.md

@@ -4,6 +4,12 @@
   aesthetics they accept: `xmin_final`, `xmax_final`, `xlower`,
   `xmiddle` and `xupper` are now valid `x` aesthetics.
 
+* `ggtitle` and `labs` now take a `subtitle` parameter which makes it 
+  possible to add a subtitle below the main plot title.
+  
+* the main plot title and subtitle are left-justified (`hjust = 0`) by
+  default
+
 # ggplot2 2.1.0
 
 ## New features

R/labels.r

@@ -28,6 +28,10 @@ update_labels <- function(p, labels) {
 #' p + ylab("New y label")
 #' p + ggtitle("New plot title")
 #'
+#' # Can add a subtitle to plots with either of the following
+#' p + ggtitle("New plot title", subtitle = "A subtitle")
+#' p + labs(title = "New plot title", subtitle = "A subtitle")
+#'
 #' # This should work independently of other functions that modify the
 #' # the scale names
 #' p + ylab("New y label") + ylim(2, 4)
@@ -38,7 +42,7 @@ update_labels <- function(p, labels) {
 #' p + labs(colour = "Cylinders")
 #'
 #' # Can also pass in a list, if that is more convenient
-#' p + labs(list(title = "Title", x = "X", y = "Y"))
+#' p + labs(list(title = "Title", subtitle = "Subtitle", x = "X", y = "Y"))
 labs <- function(...) {
   args <- list(...)
   if (is.list(args[[1]])) args <- args[[1]]
@@ -58,14 +62,12 @@ ylab <- function(label) {
 }
 #' @rdname labs
 #' @export
-ggtitle <- function(label) {
-  labs(title = label)
-}
-
-#' @rdname labs
-#' @export
-ggsubtitle <- function(label) {
-  labs(subtitle = label)
+ggtitle <- function(label, subtitle) {
+  if (!missing(subtitle)) {
+    labs(title = label, subtitle = subtitle)
+  } else {
+    labs(title = label)
+  }
 }
 
 # Convert aesthetic mapping into text labels

R/theme-defaults.r

@@ -126,10 +126,12 @@ theme_grey <- function(base_size = 11, base_family = "") {
     plot.background =    element_rect(colour = "white"),
     plot.title =         element_text(
                            size = rel(1.2),
+                           hjust = 0,
                            margin = margin(b = half_line * 1.2)
                          ),
     plot.subtitle =      element_text(
                            size = rel(0.9),
+                           hjust = 0,
                            margin = margin(b = half_line * 0.9)
                          ),
     plot.margin =        margin(half_line, half_line, half_line, half_line),

R/theme-elements.r

@@ -224,7 +224,6 @@ el_def <- function(class = NULL, inherit = NULL, description = NULL) {
   rect                = el_def("element_rect"),
   text                = el_def("element_text"),
   title               = el_def("element_text", "text"),
-  subtitle            = el_def("element_text", "text"),
   axis.line           = el_def("element_line", "line"),
   axis.text           = el_def("element_text", "text"),
   axis.title          = el_def("element_text", "title"),
@@ -279,7 +278,7 @@ el_def <- function(class = NULL, inherit = NULL, description = NULL) {
 
   plot.background     = el_def("element_rect", "rect"),
   plot.title          = el_def("element_text", "title"),
-  plot.subtitle       = el_def("element_text", "subtitle"),
+  plot.subtitle       = el_def("element_text", "title"),
   plot.margin         = el_def("margin"),
 
   aspect.ratio        = el_def("character")

R/theme.r

@@ -187,7 +187,11 @@ print.theme <- function(x, ...) utils::str(x)
 #'   plot.background  \tab background of the entire plot
 #'                    (\code{element_rect}; inherits from \code{rect}) \cr
 #'   plot.title       \tab plot title (text appearance)
-#'                    (\code{element_text}; inherits from \code{title}) \cr
+#'                    (\code{element_text}; inherits from \code{title})
+#'                    left-aligned by default\cr
+#'   plot.subtitle    \tab plot title (text appearance)
+#'                    (\code{element_text}; inherits from \code{title})
+#'                    left-aligned by default\cr
 #'   plot.margin      \tab margin around entire plot
 #'                    (\code{unit} with the sizes of the top, right, bottom, and
 #'                     left margins) \cr
@@ -254,6 +258,11 @@ print.theme <- function(x, ...) utils::str(x)
 #' p + theme(plot.title = element_text(size = rel(2)))
 #' p + theme(plot.title = element_text(size = rel(2), colour = "blue"))
 #'
+#' # Add a subtitle and adjust bottom margin
+#' p + labs(title = "Vehicle Weight-Gas Mileage Relationship",
+#'          subtitle = "You need to wrap long subtitleson manually") +
+#'     theme(plot.subtitle = element_text(margin = margin(b = 20)))
+#'
 #' # Changing plot look with themes
 #' DF <- data.frame(x = rnorm(400))
 #' m <- ggplot(DF, aes(x = x)) +