Update vignette

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

vignettes/rd.Rmd

@@ -7,7 +7,8 @@
 knitr::opts_chunk$set(
   comment = "#>",
   error = FALSE,
-  tidy = FALSE
+  tidy = FALSE,
+  collapse = TRUE
 )
 ```
 

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

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