From c0f9c95a4fb5d93e1fef738dac0c0a05e68402d6 Mon Sep 17 00:00:00 2001
From: hadley <h.wickham@gmail.com>
Date: Tue, 6 Oct 2015 14:42:56 -0400
Subject: [PATCH] Update vignette

---
 vignettes/rd.R    | 18 ++++++++++++++++--
 vignettes/rd.Rmd  |  3 ++-
 vignettes/rd.html | 21 ++++++++++++++++++++-
 vignettes/rd.md   | 24 +++++++++++++++++++++++-
 4 files changed, 61 insertions(+), 5 deletions(-)

diff --git a/vignettes/rd.R b/vignettes/rd.R
index 25785dc5e..d38581c90 100644
--- a/vignettes/rd.R
+++ b/vignettes/rd.R
@@ -1,8 +1,9 @@
-## ----, echo = FALSE, message = FALSE-------------------------------------
+## ---- echo = FALSE, message = FALSE--------------------------------------
 knitr::opts_chunk$set(
   comment = "#>",
   error = FALSE,
-  tidy = FALSE
+  tidy = FALSE,
+  collapse = TRUE
 )
 
 ## ------------------------------------------------------------------------
@@ -181,6 +182,19 @@ times <- function(x, y) x * y
 #'    Apart from the following special cases...
 #' }
 
+## ------------------------------------------------------------------------
+#' Basic arithmetic
+#'
+#' @param x,y numeric vectors.
+#' @section Neutral elements:
+#'   Addition: 0.
+add <- function(x, y) x + y
+
+#' @rdname add
+#' @section Neutral elements:
+#'   Multiplication: 1.
+times <- function(x, y) x * y
+
 ## ------------------------------------------------------------------------
 #' @backref src/file.cpp
 #' @backref src/file.h
diff --git a/vignettes/rd.Rmd b/vignettes/rd.Rmd
index 30b0cc77a..59f130119 100644
--- a/vignettes/rd.Rmd
+++ b/vignettes/rd.Rmd
@@ -7,7 +7,8 @@
 knitr::opts_chunk$set(
   comment = "#>",
   error = FALSE,
-  tidy = FALSE
+  tidy = FALSE,
+  collapse = TRUE
 )
 ```
 
diff --git a/vignettes/rd.html b/vignettes/rd.html
index 2378484f5..4572819c9 100644
--- a/vignettes/rd.html
+++ b/vignettes/rd.html
@@ -530,6 +530,7 @@ <h2>Documenting datasets</h2>
 #&#39; @source \url{http://www.diamondse.info/}
 #&#39; @name diamonds
 NULL
+#&gt; NULL
 </code></pre>
 
 <h2>Documenting packages</h2>
@@ -552,6 +553,7 @@ <h2>Documenting packages</h2>
 #&#39; @docType package
 #&#39; @name roxygen2
 NULL
+#&gt; NULL
 </code></pre>
 
 <p>Some notes:</p>
@@ -637,6 +639,7 @@ <h3>Documenting multiple functions in the same file</h3>
 #&#39; @param x,y numeric vectors.
 #&#39; @name arith
 NULL
+#&gt; NULL
 
 #&#39; @rdname arith
 add &lt;- function(x, y) x + y
@@ -647,7 +650,7 @@ <h3>Documenting multiple functions in the same file</h3>
 
 <h2>Sections</h2>
 
-<p>You can add arbitrary sections to the documentation for any object with the <code>@section</code> tag. This is a useful way of breaking a long details section into multiple chunks with useful headings. Section titles should be in sentence case and must be followed a colon. Titles may only take one line.</p>
+<p>You can add arbitrary sections to the documentation for any object with the <code>@section</code> tag. This is a useful way of breaking a long details section into multiple chunks with useful headings. Section titles should be in sentence case and must be followed by a colon. Titles may only take one line.</p>
 
 <pre><code class="r">#&#39; @section Warning:
 #&#39; Do not operate heavy machinery within 8 hours of using this function.
@@ -663,6 +666,22 @@ <h2>Sections</h2>
 #&#39; }
 </code></pre>
 
+<p>Sections with identical titles will be merged.
+This is especially useful in conjunction with the <code>@rdname</code> tag:</p>
+
+<pre><code class="r">#&#39; Basic arithmetic
+#&#39;
+#&#39; @param x,y numeric vectors.
+#&#39; @section Neutral elements:
+#&#39;   Addition: 0.
+add &lt;- function(x, y) x + y
+
+#&#39; @rdname add
+#&#39; @section Neutral elements:
+#&#39;   Multiplication: 1.
+times &lt;- function(x, y) x * y
+</code></pre>
+
 <h2>Back references</h2>
 
 <p>The original source location is added as a comment
diff --git a/vignettes/rd.md b/vignettes/rd.md
index a270d3f5a..d00ee3732 100644
--- a/vignettes/rd.md
+++ b/vignettes/rd.md
@@ -321,6 +321,7 @@ To show how everything fits together, the example below is an excerpt from the r
 #' @source \url{http://www.diamondse.info/}
 #' @name diamonds
 NULL
+#> NULL
 ```
 
 ## Documenting packages
@@ -345,6 +346,7 @@ Package documentation should be placed in `pkgname.R`. Here's an example:
 #' @docType package
 #' @name roxygen2
 NULL
+#> NULL
 ```
 
 Some notes:
@@ -432,6 +434,7 @@ Or, you can create a dummy documentation file by documenting `NULL` and setting
 #' @param x,y numeric vectors.
 #' @name arith
 NULL
+#> NULL
 
 #' @rdname arith
 add <- function(x, y) x + y
@@ -442,7 +445,7 @@ times <- function(x, y) x * y
 
 ## Sections
 
-You can add arbitrary sections to the documentation for any object with the `@section` tag. This is a useful way of breaking a long details section into multiple chunks with useful headings. Section titles should be in sentence case and must be followed a colon. Titles may only take one line.
+You can add arbitrary sections to the documentation for any object with the `@section` tag. This is a useful way of breaking a long details section into multiple chunks with useful headings. Section titles should be in sentence case and must be followed by a colon. Titles may only take one line.
 
 
 ```r
@@ -462,6 +465,25 @@ To add a subsection, you must use the `Rd` `\subsection{}` command, as follows:
 #' }
 ```
 
+Sections with identical titles will be merged.
+This is especially useful in conjunction with the `@rdname` tag:
+
+
+```r
+#' Basic arithmetic
+#'
+#' @param x,y numeric vectors.
+#' @section Neutral elements:
+#'   Addition: 0.
+add <- function(x, y) x + y
+
+#' @rdname add
+#' @section Neutral elements:
+#'   Multiplication: 1.
+times <- function(x, y) x * y
+```
+
+
 ## Back references
 
 The original source location is added as a comment