Individual vignettes for different documentation types (#1855)

And generally add more recommendations about what you should write, not just the raw structure.

Author: hadley

.gitignore

@@ -15,3 +15,4 @@ docs/
 /.Rprofile
 doc
 Meta
+.panache-cache

NEWS.md

@@ -1,6 +1,7 @@
 # roxygen2 (development version)
-* `vignette("rd-other")` now includes improved advice for documenting S3 generics, classes, and methods, including how to use the new [doclisting](https://doclisting.r-lib.org/) package to automatically list methods for a generic (#1513).
-* Added initial support for S7 classes, generics, and methods (#1484). 
+* `vignette("rd-other")` has been split into individual vignettes: `vignette("rd-datasets")`, `vignette("rd-packages")`, `vignette("rd-S3")`, `vignette("rd-S4")`, and `vignette("rd-R6")`. `vignette("rd")` has been renamed to `vignette("rd-functions")`, and the basics section has been moved to `vignette("roxygen2")`.
+* `vignette("rd-S3")` now includes improved advice for documenting S3 generics, classes, and methods, including how to use the new [doclisting](https://doclisting.r-lib.org/) package to automatically list methods for a generic (#1513).
+* Added initial support for S7 classes, generics, and methods (#1484). `vignette("rd-S7")` documents best practices.
   * S7 generics are documented like regular functions.
   * S7 classes are documented like regular functions, but you can use `@prop` to document additional properties that are not constructor parameters. If multiple classes share one page, use `@prop ClassName@prop_name description` to group properties by class. 
   * S7 methods registered with `method(generic, class) <- fn` are detected automatically and generate usage with `## S7 method for class <ClassName>`.
@@ -440,7 +441,7 @@
 
 * `@includeRmd {path.Rmd}` converts an `.Rmd`/`.md` file to `.Rd` and includes
   it in the manual page. This allows sharing text between vignettes,
-  `README.Rmd`, and the documentation. See `vignette("rd")` for details (#902).
+  `README.Rmd`, and the documentation. See `vignette("rd-functions")` for details (#902).
 
 * `@order {n}` tag controls the order in which blocks are processed. You can
   use it to override the usual ordering which proceeds from the top of
@@ -485,7 +486,7 @@
 
 ### R6
 
-roxygen2 can now document R6 classes (#922). See `vignette("rd")` for details.
+roxygen2 can now document R6 classes (#922). See `vignette("rd-R6")` for details.
 
 ### Markdown improvements
 
@@ -738,7 +739,7 @@ A big thanks goes to @mikldk for starting on the vignette and motivating me to m
 
 * `@inherits` can now inherit examples (#588).
 
-* `vignette("rd")` received a thorough updating for current best-practices.
+* `vignette("rd-functions")` received a thorough updating for current best-practices.
   The vignette still needs more work so pull requests are greatly appreciated
   (#650).
 

R/options.R

@@ -25,7 +25,7 @@
 #' * `current_package` `<string>` (read only): name of package being documented.
 #'
 #' * `rd_family_title` `<list>`: overrides for `@family` titles. See the
-#'    _rd_ vignette for details: `vignette("rd", package = "roxygen2")`
+#'    _rd-functions_ vignette for details: `vignette("rd-functions")`
 #'
 #' * `knitr_chunk_options` `<list>`: default chunk options used for knitr.
 #'

R/rd.R

@@ -3,11 +3,12 @@
 #' @description
 #' This [roclet] automates the production of the `.Rd` files that
 #' R uses to document functions, datasets, packages, classes, and more.
-#' See `vignette("rd")` for details.
+#' See `vignette("rd-functions")` for details.
 #'
 #' It is run by default by [roxygenize()].
 #'
-#' @seealso [tags-rd], [tags-rd-data], [tags-rd-oop], [tags-reuse],
+#' @seealso [tags-rd-functions], [tags-rd-datasets], [tags-rd-S3], [tags-rd-S4],
+#'   [tags-rd-S7], [tags-rd-R6], [tags-reuse],
 #'   [tags-index-crossref] for tags provided by this roclet.
 #' @export
 #' @examples

R/tag-metadata.R

@@ -69,19 +69,37 @@ tags_rd_desc <- function(tags, section) {
 
 #' Tags for documenting functions
 #'
-#' @eval tags_rd("rd")
+#' @eval tags_rd("rd-functions")
 #' @family documentation tags
 NULL
 
 #' Tags for documenting datasets
 #'
-#' @eval tags_rd("rd-data", vignette = "rd-other")
+#' @eval tags_rd("rd-datasets")
 #' @family documentation tags
 NULL
 
-#' Tags for documenting classes
+#' Tags for documenting S3
 #'
-#' @eval tags_rd("rd-oop", vignette = "rd-other")
+#' @eval tags_rd("rd-S3")
+#' @family documentation tags
+NULL
+
+#' Tags for documenting S4
+#'
+#' @eval tags_rd("rd-S4")
+#' @family documentation tags
+NULL
+
+#' Tags for documenting S7
+#'
+#' @eval tags_rd("rd-S7")
+#' @family documentation tags
+NULL
+
+#' Tags for documenting R6
+#'
+#' @eval tags_rd("rd-R6")
 #' @family documentation tags
 NULL
 

README.md

@@ -51,9 +51,11 @@ When you `roxygenise()` (or `devtools::document()`) your package these comments
 
 To get started, first read `vignette("roxygen2")`. Then read more about the specific package component that you want to generate:
 
-* Start with `vignette("rd")` to learn how document your functions with roxygen2.
+* `vignette("rd-functions")` describes how to document your functions with roxygen2.
 
-* `vignette("rd-other")` discusses how to document other things like datasets, the package itself, and the various pieces used by R's OOP systems.
+* `vignette("rd-S3")`, `vignette("rd-S4")`, `vignette("rd-R6")`, and `vignette("rd-S7")` discuss documenting the various OOP systems.
+
+* `vignette("rd-datasets")` and `vignette("rd-packages")` cover documenting datasets and the package itself.
 
 * `vignette("rd-formatting")` gives the details of roxygen2's rmarkdown support.
 

_pkgdown.yml

@@ -44,8 +44,13 @@ articles:
 - title: Documentation
   navbar: Documentation
   contents:
-  - rd
-  - rd-other
+  - rd-functions
+  - rd-S3
+  - rd-S4
+  - rd-R6
+  - rd-S7
+  - rd-datasets
+  - rd-packages
   - reuse
   - index-crossref
   - rd-formatting

inst/roxygen2-tags.yml

@@ -40,15 +40,15 @@
     A short description of the purpose of the function. Usually around
     a paragraph, but can be longer if needed.
   template: "\n${1:A short description...}\n"
-  vignette: rd
+  vignette: rd-functions
   recommend: true
 
 - name: details
   description: >
     Additional details about the function. Generally superseded by instead
     using a level 1 heading.
   template: "\n${1:Additional details...}\n"
-  vignette: rd
+  vignette: rd-functions
 
 - name: docType
   description: >
@@ -88,22 +88,22 @@
   description: >
     Embed examples stored in another file.
   template: ' ${1:path}.R'
-  vignette: rd
+  vignette: rd-functions
   recommend: true
 
 - name: examples
   description: >
     Executable R code that demonstrates how the function works. Code must run
     without error.
   template: "\n${1:# example code}\n"
-  vignette: rd
+  vignette: rd-functions
   recommend: true
 
 - name: examplesIf
   description: >
     Run examples only when `condition` is `TRUE`.
   template: " ${1:condition}\n${2:# example code}\n"
-  vignette: rd
+  vignette: rd-functions
   recommend: true
 
 - name: export
@@ -152,7 +152,7 @@
   description: >
     Describe a R6 or refClass field.
   template: ' ${1:name} ${2:description}'
-  vignette: rd-oop
+  vignette: rd-R6
   recommend: true
 
 - name: format
@@ -161,7 +161,7 @@
     include a description of each column. If not supplied, will be
     automatically generated by `object_format()`.
   template: ' ${1:description}'
-  vignette: rd-data
+  vignette: rd-datasets
   recommend: true
 
 - name: import
@@ -257,11 +257,10 @@
 
 - name: method
   description: >
-    Force a function to be recognised as an S3 method. This affects the
-    default usage and the `NAMESPACE` directive produced by `@export`.
-    Only needed if automatic detection fails.
+    If ambiguous, clarify which generic an S3 method belongs too. Only needed
+    in very rare cases.
   template: ' ${1:generic} ${2:class}'
-  vignette: rd-oop
+  vignette: rd-S3
   recommend: true
 
 - name: name
@@ -280,7 +279,7 @@
   description: >
     Suppress `.Rd` generation for a block. Use for documentation
     blocks that should only be visible in the source code.
-  vignette: 'rd'
+  vignette: rd-functions
   recommend: true
 
 - name: note
@@ -306,22 +305,23 @@
     Document multiple arguments by separating their names with commas
     without spaces.
   template: ' ${1:name} ${2:description}'
-  vignette: rd
+  vignette: rd-functions
   recommend: true
 
 - name: prop
   description: >
     Describe an S7 class property that is not a constructor parameter.
   template: ' ${1:name} ${2:description}'
-  vignette: rd-oop
+  vignette: rd-S7
   recommend: true
 
 - name: R6method
   description: >
     Document an R6 method that can't be discovered by introspection,
     such as methods added via `$set()`.
   template: ' ${1:Class}$${2:method}'
-  vignette: rd-oop
+  vignette: rd-R6
+  recommend: true
 
 - name: rawNamespace
   description: >
@@ -333,7 +333,7 @@
   description: >
     Insert literal text directly into the `.Rd` file.
   template: ' ${1:rd}'
-  vignette: rd
+  vignette: rd-functions
 
 - name: rdname
   description: >
@@ -354,15 +354,15 @@
   description: >
     Describe the function's output. Superseded in favour of `@returns`.
   template: ' ${1:description}'
-  vignette: rd
+  vignette: rd-functions
 
 - name: returns
   description: >
     Describe the function's output. Typically will be a 1-2 sentence
     description of the output type, but might also include discussion
     of important errors or warnings.
   template: ' ${1:description}'
-  vignette: rd
+  vignette: rd-functions
   recommend: true
 
 - name: section
@@ -384,7 +384,7 @@
   description: >
     Describe the slot of an S4 class.
   template: ' ${1:name} ${2:description}'
-  vignette: rd-oop
+  vignette: rd-S4
   recommend: true
 
 - name: source
@@ -393,7 +393,7 @@
     source (if possible) and briefly describe any manipulation that you
     performed when importing the data.
   template: ' ${1:description}'
-  vignette: rd-data
+  vignette: rd-datasets
   recommend: true
 
 - name: template
@@ -414,15 +414,15 @@
     An explicit `@title` is not usually needed as by default it is taken from
     the first paragraph in the roxygen block.
   template: ' ${1:title}'
-  vignette: rd
+  vignette: rd-functions
   recommend: true
 
 - name: usage
   description: >
     Override the default usage generated by roxygen2. Only needed when
     roxygen2 fails to correctly derive the usage of your function.
   template: ' ${1:fun}(${2:arg1, arg2 = default, ...})'
-  vignette: rd
+  vignette: rd-functions
   recommend: true
 
 - name: useDynLib