From 37564bd707cb02d9cc417dcba9dfd1a9c1d8f3ea Mon Sep 17 00:00:00 2001 From: hadley Date: Wed, 28 Oct 2015 14:58:40 -0500 Subject: [PATCH] Update vignettes --- vignettes/collate.R | 10 +- vignettes/collate.html | 251 +++-------- vignettes/formatting.R | 8 +- vignettes/formatting.html | 339 ++++----------- vignettes/namespace.R | 8 +- vignettes/namespace.html | 261 ++--------- vignettes/rd.R | 9 +- vignettes/rd.html | 894 +++++++++++++------------------------- vignettes/rdkeywords.R | 8 +- vignettes/rdkeywords.html | 418 ++++++------------ vignettes/roxygen2.R | 8 +- vignettes/roxygen2.html | 221 ++-------- 12 files changed, 695 insertions(+), 1740 deletions(-) diff --git a/vignettes/collate.R b/vignettes/collate.R index 56421e836..99d72d0c9 100644 --- a/vignettes/collate.R +++ b/vignettes/collate.R @@ -1,11 +1,7 @@ -## ----, echo = FALSE, message = FALSE------------------------------------- -knitr::opts_chunk$set( - comment = "#>", - error = FALSE, - tidy = FALSE -) +## ---- include = FALSE---------------------------------------------------- +knitr::opts_chunk$set(comment = "#>", collapse = TRUE) -## ----, eval = FALSE------------------------------------------------------ +## ---- eval = FALSE------------------------------------------------------- # #' @include class-a.r # setClass("B", contains = "A") diff --git a/vignettes/collate.html b/vignettes/collate.html index 16b9f336b..367220e38 100644 --- a/vignettes/collate.html +++ b/vignettes/collate.html @@ -1,223 +1,80 @@ - + + + - -Collation order + + + - + - - + - - +Collation order + + + - -

Collation order

-

R loads files in alphabetical order. Unfortunately not every alphabet puts letters in the same order, so you can't rely on alphabetic ordering if you need one file loaded before another. The order in which files are loaded doesn't matter for most packages. But if you're using S4, you'll need to make sure that classes are loaded before subclasses and generics are defined before methods.

-

Rather than relying on alphabetic ordering, roxygen2 provides an explicit way of saying that one file must be loaded before another: @include. The @include tag gives a space separated list of file names that should be loaded before the current file:

+ -
#' @include class-a.r
-setClass("B", contains = "A")
-
+

R loads files in alphabetical order. Unfortunately not every alphabet puts letters in the same order, so you can’t rely on alphabetic ordering if you need one file loaded before another. The order in which files are loaded doesn’t matter for most packages. But if you’re using S4, you’ll need to make sure that classes are loaded before subclasses and generics are defined before methods.

+

Rather than relying on alphabetic ordering, roxygen2 provides an explicit way of saying that one file must be loaded before another: @include. The @include tag gives a space separated list of file names that should be loaded before the current file:

+
#' @include class-a.r
+setClass("B", contains = "A")

If any @include tags are present in the package, roxygen2 will set the Collate field in the DESCRIPTION, which ensures that files are always loaded in the same order.

- + + + + + diff --git a/vignettes/formatting.R b/vignettes/formatting.R index 06d1f78fd..b6e1d8db9 100644 --- a/vignettes/formatting.R +++ b/vignettes/formatting.R @@ -1,9 +1,5 @@ -## ----, echo = FALSE, message = FALSE------------------------------------- -knitr::opts_chunk$set( - comment = "#>", - error = FALSE, - tidy = FALSE -) +## ---- include = FALSE---------------------------------------------------- +knitr::opts_chunk$set(comment = "#>", collapse = TRUE) ## ------------------------------------------------------------------------ #' \enumerate{ diff --git a/vignettes/formatting.html b/vignettes/formatting.html index 3d041f986..1bcca9a40 100644 --- a/vignettes/formatting.html +++ b/vignettes/formatting.html @@ -1,318 +1,161 @@ - - - -Text formatting reference sheet + - + - - + - - - - - - + - -

Text formatting reference sheet

-

Within roxygen tags, you use .Rd syntax to format text. This vignette shows you examples of the most important commands. The full details are described in R extensions.

-

Note that \ and % are special characters. To insert literals, escape with a backslash: \\, \%.

+ -

Character formatting

+

Within roxygen tags, you use .Rd syntax to format text. This vignette shows you examples of the most important commands. The full details are described in R extensions.

+

Note that \ and % are special characters. To insert literals, escape with a backslash: \\, \%.

+
+

Character formatting

- +
+ +

Lists

- - +
+

Mathematics

-

Standard LaTeX (with no extensions):

- - +
+

Tables

-

Tables are created with \tabular{}. It has two arguments:

- -
    -

  1. Column alignment, specified by letter for each column (l = left, r = right, -c = centre.)

    2. +
      +

    1. Column alignment, specified by letter for each column (l = left, r = right, c = centre.)

    2. Table contents, with columns separated by \tab and rows by \cr.

    -

    The following function turns an R data frame into into the correct format. It ignores column and row names, but should get you started.

    +
    tabular <- function(df, ...) {
+  stopifnot(is.data.frame(df))
 
-
    tabular <- function(df, ...) {
-  stopifnot(is.data.frame(df))
+  align <- function(x) if (is.numeric(x)) "r" else "l"
+  col_align <- vapply(df, align, character(1))
 
-  align <- function(x) if (is.numeric(x)) "r" else "l"
-  col_align <- vapply(df, align, character(1))
+  cols <- lapply(df, format, ...)
+  contents <- do.call("paste",
+    c(cols, list(sep = " \\tab ", collapse = "\\cr\n  ")))
 
-  cols <- lapply(df, format, ...)
-  contents <- do.call("paste",
-    c(cols, list(sep = " \\tab ", collapse = "\\cr\n  ")))
-
-  paste("\\tabular{", paste(col_align, collapse = ""), "}{\n  ",
-    contents, "\n}\n", sep = "")
+  paste("\\tabular{", paste(col_align, collapse = ""), "}{\n  ",
+    contents, "\n}\n", sep = "")
 }
 
-cat(tabular(mtcars[1:5, 1:5]))
-
    
+cat(tabular(mtcars[1:5, 1:5]))
+#> \tabular{rrrrr}{
+#>   21.0 \tab 6 \tab 160 \tab 110 \tab 3.90\cr
+#>   21.0 \tab 6 \tab 160 \tab 110 \tab 3.90\cr
+#>   22.8 \tab 4 \tab 108 \tab  93 \tab 3.85\cr
+#>   21.4 \tab 6 \tab 258 \tab 110 \tab 3.08\cr
+#>   18.7 \tab 8 \tab 360 \tab 175 \tab 3.15
+#> }
    +
-
#> \tabular{rrrrr}{
-#>   21.0 \tab 6 \tab 160 \tab 110 \tab 3.90\cr
-#>   21.0 \tab 6 \tab 160 \tab 110 \tab 3.90\cr
-#>   22.8 \tab 4 \tab 108 \tab  93 \tab 3.85\cr
-#>   21.4 \tab 6 \tab 258 \tab 110 \tab 3.08\cr
-#>   18.7 \tab 8 \tab 360 \tab 175 \tab 3.15
-#> }
-
- + + + + diff --git a/vignettes/namespace.R b/vignettes/namespace.R index 7681f5a11..cb2a7433f 100644 --- a/vignettes/namespace.R +++ b/vignettes/namespace.R @@ -1,7 +1,3 @@ -## ----, echo = FALSE, message = FALSE------------------------------------- -knitr::opts_chunk$set( - comment = "#>", - error = FALSE, - tidy = FALSE -) +## ---- include = FALSE---------------------------------------------------- +knitr::opts_chunk$set(comment = "#>", collapse = TRUE) diff --git a/vignettes/namespace.html b/vignettes/namespace.html index d681923b2..cceb7d45b 100644 --- a/vignettes/namespace.html +++ b/vignettes/namespace.html @@ -1,253 +1,88 @@ - - - -Package namespace + - + + + + + + + +Package namespace - + - -

Package namespace

-

The package NAMESPACE is one of the most confusing parts of building a package. Roxygen2 aims to make it as easy as possible to build a package that is a well-behaved member of the R ecosystem. This is a little frustrating at first, but soon becomes second-nature.

-

Exports

+ -

For a function to be usable outside of your package, you must export it. By default roxygen2 doesn't export anything from your package. If you want an object to be publically available, you must explicitly tag it with @export.

+

The package NAMESPACE is one of the most confusing parts of building a package. Roxygen2 aims to make it as easy as possible to build a package that is a well-behaved member of the R ecosystem. This is a little frustrating at first, but soon becomes second-nature.

+
+

Exports

+

For a function to be usable outside of your package, you must export it. By default roxygen2 doesn’t export anything from your package. If you want an object to be publically available, you must explicitly tag it with @export.

Use the following guidelines to decide what to export:

- - +
+

Imports

-

The NAMESPACE also controls which functions from other packages are made available to your package. Only unique directives are saved to the NAMESPACE file, so you can repeat them as needed to maintain a close link between the functions where they are needed and the namespace file.

- -

If you are using just a few functions from another package, the recommended option is to note the package name in the Imports: field of the DESCRIPTION file and call the function(s) explicitly using ::, e.g., pkg::fun(). Alternatively, though no longer recommended due to its poorer readability, use @importFrom, e.g., @importFrom pgk fun, and call the function(s) without ::.

- +

If you are using just a few functions from another package, the recommended option is to note the package name in the Imports: field of the DESCRIPTION file and call the function(s) explicitly using ::, e.g., pkg::fun(). Alternatively, though no longer recommended due to its poorer readability, use @importFrom, e.g., @importFrom pgk fun, and call the function(s) without ::.

If you are using many functions from another package, use @import package to import them all and make available without using ::.

-

If you want to add a new method to an S3 generic, import it with @importFrom pkg generic.

-

If you are using S4 you may also need:

- -

To import compiled code from another package, use @useDynLib

- +
+ - + + + + diff --git a/vignettes/rd.R b/vignettes/rd.R index 32a9a7395..6f9048d07 100644 --- a/vignettes/rd.R +++ b/vignettes/rd.R @@ -1,10 +1,5 @@ -## ---- echo = FALSE, message = FALSE-------------------------------------- -knitr::opts_chunk$set( - comment = "#>", - error = FALSE, - tidy = FALSE, - collapse = TRUE -) +## ---- include = FALSE---------------------------------------------------- +knitr::opts_chunk$set(comment = "#>", collapse = TRUE) ## ------------------------------------------------------------------------ #' Add together two numbers diff --git a/vignettes/rd.html b/vignettes/rd.html index 466d2c160..499ebc9b4 100644 --- a/vignettes/rd.html +++ b/vignettes/rd.html @@ -1,240 +1,84 @@ - - - -Generating Rd files + - + - - + - - - - - - + - -

Generating Rd files

-

Roxygen process

-

There are three steps in the transformation from roxygen comments in your source file to human readable documentation:

+ + -
    +
    +

    Roxygen process

    +

    There are three steps in the transformation from roxygen comments in your source file to human readable documentation:

    +
    1. You add roxygen comments to your source file.
    2. roxygen2::roxygenise() converts roxygen comments to .Rd files.
    3. R converts .Rd files to human readable documentation
    - -

    The process starts when you add specially formatted roxygen comments to your source file. Roxygen comments start with #' so you can continue to use regular comments for other purposes.

    - -
    #' Add together two numbers
-#'
-#' @param x A number
-#' @param y A number
-#' @return The sum of \code{x} and \code{y}
-#' @examples
-#' add(1, 1)
-#' add(10, 1)
-add <- function(x, y) {
-  x + y
-}
-
    - +

    The process starts when you add specially formatted roxygen comments to your source file. Roxygen comments start with #' so you can continue to use regular comments for other purposes.

    +
    #' Add together two numbers
+#'
+#' @param x A number
+#' @param y A number
+#' @return The sum of \code{x} and \code{y}
+#' @examples
+#' add(1, 1)
+#' add(10, 1)
+add <- function(x, y) {
+  x + y
+}

    For the example, above, this will generate man/add.Rd that looks like:

    - 
    % Generated by roxygen2 (3.2.0): do not edit by hand
 \name{add}
 \alias{add}
@@ -256,446 +100,330 @@ 
    Roxygen process
    
 \examples{
 add(1, 1)
 add(10, 1)
-}
-
    - -

    Rd files are a special file format loosely based on LaTeX. You can read more about the Rd format in the R extensions manual. I'll avoid discussing Rd files as much as possible, focussing instead on what you need to know about roxygen2.

    - +} +

    Rd files are a special file format loosely based on LaTeX. You can read more about the Rd format in the R extensions manual. I’ll avoid discussing Rd files as much as possible, focussing instead on what you need to know about roxygen2.

    When you use ?x, help("x") or example("x") R looks for an Rd file containing \alias{x}. It then parses the file, converts it into html and displays it.

    - -

    All of these functions look for an Rd file in installed packages. This isn't very useful for package development, because you want to use the .Rd files in the source package. devtools provides two helpful functions for this scenario: dev_help() and dev_example(). They behave similarly to help() and example() but look in source packages you've loaded with load_all(), not installed packages you've loaded with library().

    - +

    All of these functions look for an Rd file in installed packages. This isn’t very useful for package development, because you want to use the .Rd files in the source package. devtools provides two helpful functions for this scenario: dev_help() and dev_example(). They behave similarly to help() and example() but look in source packages you’ve loaded with load_all(), not installed packages you’ve loaded with library().

    +
    +

    Basic documentation

    - -

    Roxygen comments start with #' and include tags like @tag details. Tags break the documentation up into pieces, and the content of a tag extends from the end of tag name to the start of the next tag (or the end of the block). Because @ has a special meaning in roxygen, you need to write @@ to add a literal @ to the documentation.

    - -

    Each documentation block starts with some text. The first sentence becomes the title of the documentation. That's what you see when you look at help(package = mypackage) and is shown at the top of each help file. It should fit on one line, be written in sentence case, and end in a full stop. The second paragraph is the description: this comes first in the documentation and should briefly describe what the function does. The third and subsequent paragraphs go into the details: this is a (often long) section that comes after the argument description and should provide any other important details of how the function operates.

    - -

    Here's an example showing what the documentation for sum() might look like if it had been written with roxygen:

    - -
    #' Sum of vector elements.
-#'
-#' \code{sum} returns the sum of all the values present in its arguments.
-#'
-#' This is a generic function: methods can be defined for it directly
-#' or via the \code{\link{Summary}} group generic. For this to work properly,
-#' the arguments \code{...} should be unnamed, and dispatch is on the
-#' first argument.
-sum <- function(..., na.rm = TRUE) {}
-
    - -

    \code{} and \link{} are .Rd formatting commands which you'll learn more about in formatting. Also notice the wrapping of the roxygen block. You should make sure that your comments are less than ~80 columns wide.

    - -

    The following documentation produces the same help file as above, but uses explicit tags. You only need explicit tags if you want to the title or description to span multiple paragraphs (a bad idea), or want to omit the description (in which case roxygen will use the title for the description, since it's a required documentation component).

    - -
    #' @title Sum of vector elements.
-#'
-#' @description
-#' \code{sum} returns the sum of all the values present in its arguments.
-#'
-#' @details
-#' This is a generic function: methods can be defined for it directly
-#' or via the \code{\link{Summary}} group generic. For this to work properly,
-#' the arguments \code{...} should be unnamed, and dispatch is on the
-#' first argument.
-sum <- function(..., na.rm = TRUE) {}
-
    - +

    Roxygen comments start with #' and include tags like @tag details. Tags break the documentation up into pieces, and the content of a tag extends from the end of tag name to the start of the next tag (or the end of the block). Because @ has a special meaning in roxygen, you need to write @@ to add a literal @ to the documentation.

    +

    Each documentation block starts with some text. The first sentence becomes the title of the documentation. That’s what you see when you look at help(package = mypackage) and is shown at the top of each help file. It should fit on one line, be written in sentence case, and end in a full stop. The second paragraph is the description: this comes first in the documentation and should briefly describe what the function does. The third and subsequent paragraphs go into the details: this is a (often long) section that comes after the argument description and should provide any other important details of how the function operates.

    +

    Here’s an example showing what the documentation for sum() might look like if it had been written with roxygen:

    +
    #' Sum of vector elements.
+#'
+#' \code{sum} returns the sum of all the values present in its arguments.
+#'
+#' This is a generic function: methods can be defined for it directly
+#' or via the \code{\link{Summary}} group generic. For this to work properly,
+#' the arguments \code{...} should be unnamed, and dispatch is on the
+#' first argument.
+sum <- function(..., na.rm = TRUE) {}
    +

    \code{} and \link{} are .Rd formatting commands which you’ll learn more about in formatting. Also notice the wrapping of the roxygen block. You should make sure that your comments are less than ~80 columns wide.

    +

    The following documentation produces the same help file as above, but uses explicit tags. You only need explicit tags if you want to the title or description to span multiple paragraphs (a bad idea), or want to omit the description (in which case roxygen will use the title for the description, since it’s a required documentation component).

    +
    #' @title Sum of vector elements.
+#'
+#' @description
+#' \code{sum} returns the sum of all the values present in its arguments.
+#'
+#' @details
+#' This is a generic function: methods can be defined for it directly
+#' or via the \code{\link{Summary}} group generic. For this to work properly,
+#' the arguments \code{...} should be unnamed, and dispatch is on the
+#' first argument.
+sum <- function(..., na.rm = TRUE) {}

    All objects must have a title and description. Details are optional.

    - +

    Enhancing navigation.

    - -

    There are two tags that make it easier for people to navigate around your documentation: @seealso and @family.

    - -

    @seealso allows you to point to other useful resources, either on the web \url{http://www.r-project.org}, or to other documentation with \code{\link{functioname}}.

    - -

    If you have a family of related functions, you can use the @family <family> tag to automatically add appropriate lists and interlinks to the @seealso section. Because it will appear as “Other :”, the @family name should be plural (i.e., “model building helpers” not “model building helper”). You can make a function a member of multiple families by repeating the @family tag for each additional family. These will then get seaprate headings in the seealso section.

    - +

    There are two tags that make it easier for people to navigate around your documentation: @seealso and @family.

    +

    @seealso allows you to point to other useful resources, either on the web \url{http://www.r-project.org}, or to other documentation with \code{\link{functioname}}.

    +

    If you have a family of related functions, you can use the @family <family> tag to automatically add appropriate lists and interlinks to the @seealso section. Because it will appear as “Other :”, the @family name should be plural (i.e., “model building helpers” not “model building helper”). You can make a function a member of multiple families by repeating the @family tag for each additional family. These will then get seaprate headings in the seealso section.

    For sum, these components might look like:

    - -
    #' @family aggregate functions
-#' @seealso \code{\link{prod}} for products, \code{\link{cumsum}} for
-#'  cumulative sums, and \code{\link{colSums}}/\code{\link{rowSums}}
-#'  marginal sums over high-dimensional arrays.
-
    - +
    #' @family aggregate functions
+#' @seealso \code{\link{prod}} for products, \code{\link{cumsum}} for
+#'  cumulative sums, and \code{\link{colSums}}/\code{\link{rowSums}}
+#'  marginal sums over high-dimensional arrays.

    Three other tags make it easier for the user to find documentation:

    -
      -

    • @aliases space separated aliases to add additional aliases, through -which the user can find the documentation with ?.

      • +

    • @aliases space separated aliases to add additional aliases, through which the user can find the documentation with ?.

    • @concept to add extra keywords that will be found with help.search()

      • -

    • @keywords keyword1 keyword2 ... to add standardised keywords. Keywords are -optional, but if present, must be taken from the predefined list replicated -in the keywords vignette. Keywords are not very useful, -except for @keywords internal. Using the internal keyword removes all functions -in the associated .Rd file from the documentation index and disables some of -their automated tests. -A common use case is to both export a function (using @export) and marking it as -internal. That way, advanced users can access a function that new users would be confused -about if they were to see it in the index.

      • +

    • @keywords keyword1 keyword2 ... to add standardised keywords. Keywords are optional, but if present, must be taken from the predefined list replicated in the keywords vignette. Keywords are not very useful, except for @keywords internal. Using the internal keyword removes all functions in the associated .Rd file from the documentation index and disables some of their automated tests. A common use case is to both export a function (using @export) and marking it as internal. That way, advanced users can access a function that new users would be confused about if they were to see it in the index.

    - -

    You use other tags based on the type of object that you're documenting. The following sections describe the most commonly used tags for functions, S3, S4 and RC objects and data.

    - +

    You use other tags based on the type of object that you’re documenting. The following sections describe the most commonly used tags for functions, S3, S4 and RC objects and data.

    +
    +
    +

    Documenting functions

    -

    Functions are the mostly commonly documented objects. Most functions use three tags:

    -
      -

    • @param name description describes the inputs to the function. -The description should provide a succinct summary of the type of the -parameter (e.g. a string, a numeric vector), and if not obvious from -the name, what the parameter does. The description should start with a -capital letter and end with a full stop. It can span multiple lines (or -even paragraphs) if necessary. All parameters must be documented.

      - -

      You can document multiple arguments in one place by separating -the names with commas (no spaces). For example, to document both -x and y, you can say @param x,y Numeric vectors.

      • -

    • @examples provides executable R code showing how to use the function in -practice. This is a very important part of the documentation because -many people look at the examples before reading anything. Example code -must work without errors as it is run automatically as part of R CMD -check.

      - -

      However for the purpose of illustration, it's often useful to include code -that causes an error. \dontrun{} allows you to include code in the -example that is never used. There are two other special commands. -\dontshow{} is run, but not shown in the help page: this can -be useful for informal tests. \donttest{} is run in examples, -but not run automatically in R CMD check. This is useful if you -have examples that take a long time to run. The options are summarised -below.

      - - - - - - - +

    • @param name description describes the inputs to the function. The description should provide a succinct summary of the type of the parameter (e.g. a string, a numeric vector), and if not obvious from the name, what the parameter does. The description should start with a capital letter and end with a full stop. It can span multiple lines (or even paragraphs) if necessary. All parameters must be documented.

      +

      You can document multiple arguments in one place by separating the names with commas (no spaces). For example, to document both x and y, you can say @param x,y Numeric vectors.

      • +

    • @examples provides executable R code showing how to use the function in practice. This is a very important part of the documentation because many people look at the examples before reading anything. Example code must work without errors as it is run automatically as part of R CMD check.

      +

      However for the purpose of illustration, it’s often useful to include code that causes an error. \dontrun{} allows you to include code in the example that is never used. There are two other special commands. \dontshow{} is run, but not shown in the help page: this can be useful for informal tests. \donttest{} is run in examples, but not run automatically in R CMD check. This is useful if you have examples that take a long time to run. The options are summarised below.

      +
      • CommandexamplehelpR CMD check
      + + + + + + - - - - - - + + + + + + - - - - - + + + + + - - - - - + + + + -
      CommandexamplehelpR CMD check
      \dontrun{}x
      \dontrun{}x
      \dontshow{}xx
      \dontshow{}xx
      \donttest{}xx
      \donttest{}xx
      - -

      Instead of including examples directly in the documentation, you can -put them in separate files and use @example path/relative/to/packge/root -to insert them into the documentation.

      • -

    • @return description describes the output from the function. This is -not always necessary, but is a good idea if you return different types -of outputs depending on the input, or you're returning an S3, S4 or RC -object.

      • + + +

      Instead of including examples directly in the documentation, you can put them in separate files and use @example path/relative/to/packge/root to insert them into the documentation.

      +

    • @return description describes the output from the function. This is not always necessary, but is a good idea if you return different types of outputs depending on the input, or you’re returning an S3, S4 or RC object.

    -

    We could use these new tags to improve our documentation of sum() as follows:

    - -
    #' Sum of vector elements.
-#'
-#' \code{sum} returns the sum of all the values present in its arguments.
-#'
-#' This is a generic function: methods can be defined for it directly
-#' or via the \code{\link{Summary}} group generic. For this to work properly,
-#' the arguments \code{...} should be unnamed, and dispatch is on the
-#' first argument.
-#'
-#' @param ... Numeric, complex, or logical vectors.
-#' @param na.rm A logical scalar. Should missing values (including NaN)
-#'   be removed?
-#' @return If all inputs are integer and logical, then the output
-#'   will be an integer. If integer overflow
-#'   \url{http://en.wikipedia.org/wiki/Integer_overflow} occurs, the output
-#'   will be NA with a warning. Otherwise it will be a length-one numeric or
-#'   complex vector.
-#'
-#'   Zero-length vectors have sum 0 by definition. See
-#'   \url{http://en.wikipedia.org/wiki/Empty_sum} for more details.
-#' @examples
-#' sum(1:10)
-#' sum(1:5, 6:10)
-#' sum(F, F, F, T, T)
-#'
-#' sum(.Machine$integer.max, 1L)
-#' sum(.Machine$integer.max, 1)
-#'
-#' \dontrun{
-#' sum("a")
-#' }
-sum <- function(..., na.rm = TRUE) {}
-
    - -

    Indent the second and subsequent lines of a tag so that when scanning the documentation so it's easy to see where one tag ends and the next begins. Tags that always span multiple lines (like @example) should start on a new line and don't need to be indented.

    - +
    #' Sum of vector elements.
+#'
+#' \code{sum} returns the sum of all the values present in its arguments.
+#'
+#' This is a generic function: methods can be defined for it directly
+#' or via the \code{\link{Summary}} group generic. For this to work properly,
+#' the arguments \code{...} should be unnamed, and dispatch is on the
+#' first argument.
+#'
+#' @param ... Numeric, complex, or logical vectors.
+#' @param na.rm A logical scalar. Should missing values (including NaN)
+#'   be removed?
+#' @return If all inputs are integer and logical, then the output
+#'   will be an integer. If integer overflow
+#'   \url{http://en.wikipedia.org/wiki/Integer_overflow} occurs, the output
+#'   will be NA with a warning. Otherwise it will be a length-one numeric or
+#'   complex vector.
+#'
+#'   Zero-length vectors have sum 0 by definition. See
+#'   \url{http://en.wikipedia.org/wiki/Empty_sum} for more details.
+#' @examples
+#' sum(1:10)
+#' sum(1:5, 6:10)
+#' sum(F, F, F, T, T)
+#'
+#' sum(.Machine$integer.max, 1L)
+#' sum(.Machine$integer.max, 1)
+#'
+#' \dontrun{
+#' sum("a")
+#' }
+sum <- function(..., na.rm = TRUE) {}
    +

    Indent the second and subsequent lines of a tag so that when scanning the documentation so it’s easy to see where one tag ends and the next begins. Tags that always span multiple lines (like @example) should start on a new line and don’t need to be indented.

    +
    +

    Documenting classes, generics and methods

    -

    Documenting classes, generics and methods are relatively straightforward, but there are some variations based on the object system. The following sections give the details for the S3, S4 and RC object systems.

    - +

    S3

    - -

    S3 generics are regular functions, so document them as such. S3 classes have no formal definition, so document the constructor function. It is your choice whether or not to document S3 methods. You don't need to document methods for simple generics like print(). If your method is more complicated, you should document it so people know what the parameters do. In base R, you can find documentation for more complex methods like predict.lm(), predict.glm(), and anova.glm().

    - +

    S3 generics are regular functions, so document them as such. S3 classes have no formal definition, so document the constructor function. It is your choice whether or not to document S3 methods. You don’t need to document methods for simple generics like print(). If your method is more complicated, you should document it so people know what the parameters do. In base R, you can find documentation for more complex methods like predict.lm(), predict.glm(), and anova.glm().

    Older versions of roxygen required explicit @method generic class tags for all S3 methods. From 3.0.0 this is no longer needed as and roxygen2 will figure it out automatically. If you are upgrading, make sure to remove these old tags. Automatic method detection will only fail if the generic and class are ambiguous. For example is all.equal.data.frame() the equal.data.frame method for all, or the data.frame method for all.equal?. If this happens, you can disambiguate with (e.g.) @method all.equal data.frame.

    - +
    +

    S4

    - -

    Older versions of roxyen2 required explicit @usage, @alias and @docType to correctly document S4 objects, but from version 3.0.0 on roxygen2 generates correct metadata automatically. If you're upgrading from a previous version, make sure to remove these old tags.

    - -

    S4 generics are also functions, so document them as such. Document S4 classes by adding a roxygen block before setClass(). Use @slot to document the slots of the class. Here's a simple example:

    - -
    #' An S4 class to represent a bank account.
-#'
-#' @slot balance A length-one numeric vector
-Account <- setClass("Account",
-  slots = list(balance = "numeric")
-)
-
    - +

    Older versions of roxyen2 required explicit @usage, @alias and @docType to correctly document S4 objects, but from version 3.0.0 on roxygen2 generates correct metadata automatically. If you’re upgrading from a previous version, make sure to remove these old tags.

    +

    S4 generics are also functions, so document them as such. Document S4 classes by adding a roxygen block before setClass(). Use @slot to document the slots of the class. Here’s a simple example:

    +
    #' An S4 class to represent a bank account.
+#'
+#' @slot balance A length-one numeric vector
+Account <- setClass("Account",
+  slots = list(balance = "numeric")
+)

    S4 methods are a little more complicated. Unlike S3, all S4 methods must be documented. You can document them in three places:

    -
      -

    • In the class. Most appropriate if the corresponding generic uses single -dispatch and you created the class.

      • -

    • In the generic. Most appropriate if the generic uses multiple dispatch -and you control it.

      • -

    • In its own file. Most appropriate if the method is complex. or the -either two options don't apply.

      • +

    • In the class. Most appropriate if the corresponding generic uses single dispatch and you created the class.

      • +

    • In the generic. Most appropriate if the generic uses multiple dispatch and you control it.

      • +

    • In its own file. Most appropriate if the method is complex. or the either two options don’t apply.

    -

    Use either @rdname or @describeIn to control where method documentation goes. See the next section for more details.

    - +
    +

    RC

    -

    RC is different to S3 and S4 because methods are associated with classes, not generics. RC also has a special convention for documenting methods: the docstring. This makes documenting RC simpler than S4 because you only need one roxygen block per class.

    - -
    #' A Reference Class to represent a bank account.
-#'
-#' @field balance A length-one numeric vector
-Account <- setRefClass("Account",
-  fields = list(balance = "numeric"),
-  methods = list(
-    withdraw = function(x) {
-      "Withdraw money from account. Allows overdrafts"
-      balance <<- balance - x
+
    #' A Reference Class to represent a bank account.
+#'
+#' @field balance A length-one numeric vector
+Account <- setRefClass("Account",
+  fields = list(balance = "numeric"),
+  methods = list(
+    withdraw = function(x) {
+      "Withdraw money from account. Allows overdrafts"
+      balance <<- balance - x
     }
   )
-)
-
    
-
-
    Methods with doc strings will be included in the “Methods” section of the class documentation. Each documented method will be listed with an automatically generated usage statement and its doc string.
    
-
+)
    +

    Methods with doc strings will be included in the “Methods” section of the class documentation. Each documented method will be listed with an automatically generated usage statement and its doc string.

    +
    +
    +

    Documenting datasets

    - -

    Datasets are usually stored as .rdata files in data/ and not as regular R objects in the package. This means you need document them slightly differently: instead of documenting the data directly, you quote the dataset's name.

    - +

    Datasets are usually stored as .rdata files in data/ and not as regular R objects in the package. This means you need document them slightly differently: instead of documenting the data directly, you quote the dataset’s name.

    There are two additional tags that are useful for documenting datasets:

    -
      -

    • @format, which gives an overview of the structure of the dataset. -If you omit this, roxygen will automatically add something based on the -first line of str() output

      • +

    • @format, which gives an overview of the structure of the dataset. If you omit this, roxygen will automatically add something based on the first line of str() output

    • @source where you got the data form, often a \url{}.

    -

    To show how everything fits together, the example below is an excerpt from the roxygen block used to document the diamonds dataset in ggplot2.

    - -
    #' Prices of 50,000 round cut diamonds.
-#'
-#' A dataset containing the prices and other attributes of almost 54,000
-#' diamonds. The variables are as follows:
-#'
-#' \itemize{
-#'   \item price. price in US dollars (\$326--\$18,823)
-#'   \item carat. weight of the diamond (0.2--5.01)
-#'   ...
-#' }
-#'
-#' @format A data frame with 53940 rows and 10 variables
-#' @source \url{http://www.diamondse.info/}
-"diamonds"
-#> [1] "diamonds"
-
    - +
    #' Prices of 50,000 round cut diamonds.
+#'
+#' A dataset containing the prices and other attributes of almost 54,000
+#' diamonds. The variables are as follows:
+#'
+#' \itemize{
+#'   \item price. price in US dollars (\$326--\$18,823)
+#'   \item carat. weight of the diamond (0.2--5.01)
+#'   ...
+#' }
+#'
+#' @format A data frame with 53940 rows and 10 variables
+#' @source \url{http://www.diamondse.info/}
+"diamonds"
+#> [1] "diamonds"
    +
    +

    Documenting packages

    - -

    As well as documenting every exported object in the package, you should also document the package itself. Relatively few packages provide package documentation, but it's an extremely useful tool for users, because instead of just listing functions like help(package = pkgname) it organises them and shows the user where to get started.

    - +

    As well as documenting every exported object in the package, you should also document the package itself. Relatively few packages provide package documentation, but it’s an extremely useful tool for users, because instead of just listing functions like help(package = pkgname) it organises them and shows the user where to get started.

    Package documentation should describe the overall purpose of the package and point to the most important functions. It should not contain a verbatim list of functions or copy of DESCRIPTION (although title and description are inherited from DESCRIPTION by default to help you get started). This file is for human reading, so pick the most important elements of your package.

    - -

    Package documentation should be placed in pkgname.R. Here's an example:

    - -
    #' Generate R documentation from inline comments.
-#'
-#' Roxygen2 allows you to write documentation in comment blocks co-located
-#' with code.
-#'
-#' The only function you're likely to need from \pkg{roxygen2} is
-#' \code{\link{roxygenize}}. Otherwise refer to the vignettes to see
-#' how to format the documentation.
-"_PACKAGE"
-#> [1] "_PACKAGE"
-
    - +

    Package documentation should be placed in pkgname.R. Here’s an example:

    +
    #' Generate R documentation from inline comments.
+#'
+#' Roxygen2 allows you to write documentation in comment blocks co-located
+#' with code.
+#'
+#' The only function you're likely to need from \pkg{roxygen2} is
+#' \code{\link{roxygenize}}. Otherwise refer to the vignettes to see
+#' how to format the documentation.
+"_PACKAGE"
+#> [1] "_PACKAGE"

    Some notes:

    -
      -

    • Like for datasets, there isn't a object that we can document directly. Use -"_PACKAGE" to indicate that you are creating the package's documentation. -This will automatically add the corect aliases so that both ?pkgname -and package?pkgname will find the package help. This also works if there's -already a function called pkgname().

      • -

    • Use @references point to published material about the package that -users might find helpful.

      • +

    • Like for datasets, there isn’t a object that we can document directly. Use "_PACKAGE" to indicate that you are creating the package’s documentation. This will automatically add the corect aliases so that both ?pkgname and package?pkgname will find the package help. This also works if there’s already a function called pkgname().

      • +

    • Use @references point to published material about the package that users might find helpful.

    - -

    Package documentation is a good place to list all options() that a package understands and to document their behaviour. Put in a section called “Package options”, as described below.

    - +

    Package documentation is a good place to list all options() that a package understands and to document their behaviour. Put in a section called “Package options”, as described below.

    +
    +

    Do repeat yourself

    - -

    There is a tension between the DRY (do not repeat yourself) principle of programming and the need for documentation to be self-contained. It's frustrating to have to navigate through multiple help files in order to pull together all the pieces you need. Roxygen2 provides three ways to avoid repeating yourself in code documentation, while assembling information from multiple places in one documentation file:

    - +

    There is a tension between the DRY (do not repeat yourself) principle of programming and the need for documentation to be self-contained. It’s frustrating to have to navigate through multiple help files in order to pull together all the pieces you need. Roxygen2 provides three ways to avoid repeating yourself in code documentation, while assembling information from multiple places in one documentation file:

    • create reusable with templates with @template and @templateVar
    • reuse parameter documentation with @inheritParams
    • document multiple functions in the same place with @describeIn or @rdname
    - +

    Roxygen templates

    -

    Roxygen templates are R files containing only roxygen comments that live in the man-roxygen directory. Use @template file-name (without extension) to insert the contents of a template into the current documentation.

    -

    You can make templates more flexible by using template variables defined with @templateVar name value. Template files are run with brew, so you can retrieve values (or execute any other arbitrary R code) with <%= name %>.

    - -

    Note that templates are parsed a little differently to regular blocks, so you'll need to explicitly set the title, description and details with @title, @description and @details.

    - +

    Note that templates are parsed a little differently to regular blocks, so you’ll need to explicitly set the title, description and details with @title, @description and @details.

    +
    +

    Inheriting parameters from other functions

    -

    You can inherit parameter descriptions from other functions using @inheritParams source_function. This tag will bring in all documentation for parameters that are undocumented in the current function, but documented in the source function. The source can be a function in the current package, @inheritParams function, or another package using @inheritParams package::function.

    -

    Note, however, that inheritance does not chain. In other words, the source_function must always be the function that defines the parameter using @param.

    - +
    +

    Documenting multiple functions in the same file

    - -

    You can document multiple functions in the same file by using either @rdname or @describeIn tag. It's a technique best used with caution: documenting too many functions into one place leads to confusing documentation. It's best used when all functions have the same (or very similar) arguments.

    - +

    You can document multiple functions in the same file by using either @rdname or @describeIn tag. It’s a technique best used with caution: documenting too many functions into one place leads to confusing documentation. It’s best used when all functions have the same (or very similar) arguments.

    @describeIn is designed for the most common cases:

    -
    • documenting methods in a generic
    • documenting methods in a class
    • documenting functions with the same (or similar arguments)
    - -

    It generates a new section, named either “Methods (by class)”, “Methods (by generic)” or “Functions”. The section contains a bulleted list describing each function, labelled so that you know what function or method it's talking about. Here's an example, documenting an imaginary new generic:

    - -
    #' Foo bar generic
-#'
-#' @param x Object to foo.
-foobar <- function(x) UseMethod("x")
-
-#' @describeIn foobar Difference between the mean and the median
-foobar.numeric <- function(x) abs(mean(x) - median(x))
-
-#' @describeIn foobar First and last values pasted together in a string.
-foobar.character <- function(x) paste0(x[1], "-", x[length(x)])
-
    - -

    An alternative to @describeIn is @rdname. It overrides the default file name generated by roxygen and merges documentation for multiple objects into one file. This gives you complete freedom to combine documentation however you see fit. There are two ways to use @rdname. You can add documentation to an existing function:

    - -
    #' Basic arithmetic
-#'
-#' @param x,y numeric vectors.
-add <- function(x, y) x + y
-
-#' @rdname add
-times <- function(x, y) x * y
-
    - +

    It generates a new section, named either “Methods (by class)”, “Methods (by generic)” or “Functions”. The section contains a bulleted list describing each function, labelled so that you know what function or method it’s talking about. Here’s an example, documenting an imaginary new generic:

    +
    #' Foo bar generic
+#'
+#' @param x Object to foo.
+foobar <- function(x) UseMethod("x")
+
+#' @describeIn foobar Difference between the mean and the median
+foobar.numeric <- function(x) abs(mean(x) - median(x))
+
+#' @describeIn foobar First and last values pasted together in a string.
+foobar.character <- function(x) paste0(x[1], "-", x[length(x)])
    +

    An alternative to @describeIn is @rdname. It overrides the default file name generated by roxygen and merges documentation for multiple objects into one file. This gives you complete freedom to combine documentation however you see fit. There are two ways to use @rdname. You can add documentation to an existing function:

    +
    #' Basic arithmetic
+#'
+#' @param x,y numeric vectors.
+add <- function(x, y) x + y
+
+#' @rdname add
+times <- function(x, y) x * y

    Or, you can create a dummy documentation file by documenting NULL and setting an informative @name.

    - -
    #' Basic arithmetic
-#'
-#' @param x,y numeric vectors.
-#' @name arith
-NULL
-#> NULL
-
-#' @rdname arith
-add <- function(x, y) x + y
-
-#' @rdname arith
-times <- function(x, y) x * y
-
    - +
    #' Basic arithmetic
+#'
+#' @param x,y numeric vectors.
+#' @name arith
+NULL
+#> NULL
+
+#' @rdname arith
+add <- function(x, y) x + y
+
+#' @rdname arith
+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 by a colon. Titles may only take one line.

    - -
    #' @section Warning:
-#' Do not operate heavy machinery within 8 hours of using this function.
-
    - +
    #' @section Warning:
+#' Do not operate heavy machinery within 8 hours of using this function.

    To add a subsection, you must use the Rd \subsection{} command, as follows:

    - -
    #' @section Warning:
-#' You must not call this function unless ...
-#'
-#' \subsection{Exceptions}{
-#'    Apart from the following special cases...
-#' }
-
    - -

    Sections with identical titles will be merged. -This is especially useful in conjunction with the @rdname tag:

    - -
    #' 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
-
    - +
    #' @section Warning:
+#' You must not call this function unless ...
+#'
+#' \subsection{Exceptions}{
+#'    Apart from the following special cases...
+#' }
    +

    Sections with identical titles will be merged. This is especially useful in conjunction with the @rdname tag:

    +
    #' 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 -to the second line of each generated .Rd file in the following form:

    - -
    % Please edit documentation in ...
-
    - -

    roxygen2 tries to capture all locations from which the documentation is assembled. -For code that generates R code with Roxygen comments (e.g., the Rcpp package), -the @backref tag is provided. -This allows specifying the “true” source of the documentation, -and will substitute the default list of source files. -Use one tag per source file:

    - -
    #' @backref src/file.cpp
-#' @backref src/file.h
-
    +

    The original source location is added as a comment to the second line of each generated .Rd file in the following form:

    +
    % Please edit documentation in ...
    +

    roxygen2 tries to capture all locations from which the documentation is assembled. For code that generates R code with Roxygen comments (e.g., the Rcpp package), the @backref tag is provided. This allows specifying the “true” source of the documentation, and will substitute the default list of source files. Use one tag per source file:

    +
    #' @backref src/file.cpp
+#' @backref src/file.h
    +
    + + + + + - diff --git a/vignettes/rdkeywords.R b/vignettes/rdkeywords.R index 8887d4585..cbabc282d 100644 --- a/vignettes/rdkeywords.R +++ b/vignettes/rdkeywords.R @@ -1,9 +1,5 @@ -## ----, echo = FALSE, message = FALSE------------------------------------- -knitr::opts_chunk$set( - comment = "#>", - error = FALSE, - tidy = FALSE -) +## ---- include = FALSE---------------------------------------------------- +knitr::opts_chunk$set(comment = "#>", collapse = TRUE) ## ------------------------------------------------------------------------ cat(readLines(file.path(R.home("doc"), "KEYWORDS")), sep = "\n") diff --git a/vignettes/rdkeywords.html b/vignettes/rdkeywords.html index b0cfa8df1..d6076d5b0 100644 --- a/vignettes/rdkeywords.html +++ b/vignettes/rdkeywords.html @@ -1,305 +1,163 @@ - - - -Keywords + - + - - + - - - - - - + - -

    Keywords

    -
    cat(readLines(file.path(R.home("doc"), "KEYWORDS")), sep = "\n")
-
    -
    #> GROUPED Keywords
-#> ----------------
-#> 
-#> Graphics
-#>  aplot       &   Add to Existing Plot / internal plot
-#>  dplot       &   Computations Related to Plotting
-#>  hplot       &   High-Level Plots
-#>  iplot       &   Interacting with Plots
-#>  color       &   Color, Palettes etc
-#>  dynamic     &   Dynamic Graphics
-#>  device      &   Graphical Devices
-#> 
-#> Basics
-#>  sysdata     &   Basic System Variables      [!= S]
-#>  datasets    &   Datasets available by data(.)   [!= S]
-#>  data        &   Environments, Scoping, Packages [~= S]
-#>  manip       &   Data Manipulation
-#>  attribute   &   Data Attributes
-#>  classes     &   Data Types (not OO)
-#>      & character &   Character Data ("String") Operations
-#>      & complex   &   Complex Numbers
-#>      & category  &   Categorical Data
-#>      & NA    &   Missing Values          [!= S]
-#>  list        &   Lists
-#>  chron       &   Dates and Times
-#>  package     &   Package Summaries
-#> 
-#> Mathematics
-#>  array       &   Matrices and Arrays
-#>        & algebra &   Linear Algebra
-#>  arith       &   Basic Arithmetic and Sorting    [!= S]
-#>  math        &   Mathematical Calculus etc.  [!= S]
-#>  logic       &   Logical Operators
-#>  optimize    &   Optimization
-#>  symbolmath  &   "Symbolic Math", as polynomials, fractions
-#>  graphs      &   Graphs, (not graphics), e.g. dendrograms
-#> 
-#> Programming, Input/Ouput, and Miscellaneous
-#> 
-#>  programming &   Programming
-#>       & interface&   Interfaces to Other Languages
-#>  IO      &   Input/output
-#>       & file &   Files
-#>       & connection&  Connections
-#>       & database &   Interfaces to databases
-#>  iteration   &   Looping and Iteration
-#>  methods     &   Methods and Generic Functions
-#>  print       &   Printing
-#>  error       &   Error Handling
-#> 
-#>  environment &   Session Environment
-#>  internal    &   Internal Objects (not part of API)
-#>  utilities   &   Utilities
-#>  misc        &   Miscellaneous
-#>  documentation   &   Documentation
-#>  debugging   &   Debugging Tools
-#> 
-#> Statistics
-#> 
-#>  datagen     &   Functions for generating data sets
-#>  distribution    &   Probability Distributions and Random Numbers
-#>  univar      &   simple univariate statistics  [!= S]
-#>  htest       &   Statistical Inference
-#>  models      &   Statistical Models
-#>      & regression&   Regression
-#>      & &nonlinear&   Non-linear Regression (only?)
-#>  robust      &   Robust/Resistant Techniques
-#>  design      &   Designed Experiments
-#>  multivariate    &   Multivariate Techniques
-#>  ts      &   Time Series
-#>  survival    &   Survival Analysis
-#>  nonparametric   &   Nonparametric Statistics [w/o 'smooth']
-#>  smooth      &   Curve (and Surface) Smoothing
-#>       & loess    &   Loess Objects
-#>  cluster     &   Clustering
-#>  tree        &   Regression and Classification Trees
-#>  survey      &   Complex survey samples
-#> 
-#> 
-#> MASS (2, 1997)
-#> --------------
-#> 
-#> add the following keywords :
-#> 
-#>  classif     &   Classification  ['class' package]
-#>  spatial     &   Spatial Statistics ['spatial' package]
-#>  neural      &   Neural Networks ['nnet'  package]
-
    + + + +
    cat(readLines(file.path(R.home("doc"), "KEYWORDS")), sep = "\n")
+#> GROUPED Keywords
+#> ----------------
+#> 
+#> Graphics
+#>  aplot       &   Add to Existing Plot / internal plot
+#>  dplot       &   Computations Related to Plotting
+#>  hplot       &   High-Level Plots
+#>  iplot       &   Interacting with Plots
+#>  color       &   Color, Palettes etc
+#>  dynamic     &   Dynamic Graphics
+#>  device      &   Graphical Devices
+#> 
+#> Basics
+#>  sysdata     &   Basic System Variables      [!= S]
+#>  datasets    &   Datasets available by data(.)   [!= S]
+#>  data        &   Environments, Scoping, Packages [~= S]
+#>  manip       &   Data Manipulation
+#>  attribute   &   Data Attributes
+#>  classes     &   Data Types (not OO)
+#>      & character &   Character Data ("String") Operations
+#>      & complex   &   Complex Numbers
+#>      & category  &   Categorical Data
+#>      & NA    &   Missing Values          [!= S]
+#>  list        &   Lists
+#>  chron       &   Dates and Times
+#>  package     &   Package Summaries
+#> 
+#> Mathematics
+#>  array       &   Matrices and Arrays
+#>        & algebra &   Linear Algebra
+#>  arith       &   Basic Arithmetic and Sorting    [!= S]
+#>  math        &   Mathematical Calculus etc.  [!= S]
+#>  logic       &   Logical Operators
+#>  optimize    &   Optimization
+#>  symbolmath  &   "Symbolic Math", as polynomials, fractions
+#>  graphs      &   Graphs, (not graphics), e.g. dendrograms
+#> 
+#> Programming, Input/Ouput, and Miscellaneous
+#> 
+#>  programming &   Programming
+#>       & interface&   Interfaces to Other Languages
+#>  IO      &   Input/output
+#>       & file &   Files
+#>       & connection&  Connections
+#>       & database &   Interfaces to databases
+#>  iteration   &   Looping and Iteration
+#>  methods     &   Methods and Generic Functions
+#>  print       &   Printing
+#>  error       &   Error Handling
+#> 
+#>  environment &   Session Environment
+#>  internal    &   Internal Objects (not part of API)
+#>  utilities   &   Utilities
+#>  misc        &   Miscellaneous
+#>  documentation   &   Documentation
+#>  debugging   &   Debugging Tools
+#> 
+#> Statistics
+#> 
+#>  datagen     &   Functions for generating data sets
+#>  distribution    &   Probability Distributions and Random Numbers
+#>  univar      &   simple univariate statistics  [!= S]
+#>  htest       &   Statistical Inference
+#>  models      &   Statistical Models
+#>      & regression&   Regression
+#>      & &nonlinear&   Non-linear Regression (only?)
+#>  robust      &   Robust/Resistant Techniques
+#>  design      &   Designed Experiments
+#>  multivariate    &   Multivariate Techniques
+#>  ts      &   Time Series
+#>  survival    &   Survival Analysis
+#>  nonparametric   &   Nonparametric Statistics [w/o 'smooth']
+#>  smooth      &   Curve (and Surface) Smoothing
+#>       & loess    &   Loess Objects
+#>  cluster     &   Clustering
+#>  tree        &   Regression and Classification Trees
+#>  survey      &   Complex survey samples
+#> 
+#> 
+#> MASS (2, 1997)
+#> --------------
+#> 
+#> add the following keywords :
+#> 
+#>  classif     &   Classification  ['class' package]
+#>  spatial     &   Spatial Statistics ['spatial' package]
+#>  neural      &   Neural Networks ['nnet'  package]
    + + + + + - diff --git a/vignettes/roxygen2.R b/vignettes/roxygen2.R index 7681f5a11..cb2a7433f 100644 --- a/vignettes/roxygen2.R +++ b/vignettes/roxygen2.R @@ -1,7 +1,3 @@ -## ----, echo = FALSE, message = FALSE------------------------------------- -knitr::opts_chunk$set( - comment = "#>", - error = FALSE, - tidy = FALSE -) +## ---- include = FALSE---------------------------------------------------- +knitr::opts_chunk$set(comment = "#>", collapse = TRUE) diff --git a/vignettes/roxygen2.html b/vignettes/roxygen2.html index 24f442197..3eb07107a 100644 --- a/vignettes/roxygen2.html +++ b/vignettes/roxygen2.html @@ -1,213 +1,72 @@ - - - -Introduction to roxygen2 + - + + + + + + +Introduction to roxygen2 - + + - -

    Introduction to roxygen2

    -

    Documentation is one of the most important aspects of good code. Without it, users won't know how to use your package, and are unlikely to do so. Documentation is also useful for you in the future (so you remember what the heck you were thinking!), and for other developers working on your package. The goal of roxygen2 is to make documenting your code as easy as possible. R provides a standard way of documenting packages: you write .Rd files in the man/ directory. These files use a custom syntax, loosely based on latex. Roxygen2 provides a number of advantages over writing .Rd files by hand:

    + + + +

    Documentation is one of the most important aspects of good code. Without it, users won’t know how to use your package, and are unlikely to do so. Documentation is also useful for you in the future (so you remember what the heck you were thinking!), and for other developers working on your package. The goal of roxygen2 is to make documenting your code as easy as possible. R provides a standard way of documenting packages: you write .Rd files in the man/ directory. These files use a custom syntax, loosely based on latex. Roxygen2 provides a number of advantages over writing .Rd files by hand:

    -

    As well as generating .Rd files, roxygen will also create a NAMESPACE for you, and will manage the Collate field in DESCRIPTION.

    -

    This vignette provides a high-level description of roxygen2 and how the three main components work. The other vignettes provide more detail on the individual components:

    - - +

    Running roxygen

    -

    There are three main ways to run roxygen:

    -

    • roxygen2::roxygenise(), or

      • -

    • devtools::document(), if you're using devtools, or

      • -

    • Ctrl + Shift + D, if you're using RStudio.

      • +

    • devtools::document(), if you’re using devtools, or

      • +

    • Ctrl + Shift + D, if you’re using RStudio.

    +

    As of version 4.0.0, roxygen2 will never overwrite a file it didn’t create. It does this by labelling every file it creates with a comment: “Generated by roxygen2 (version): do not edit by hand”.

    +
    -

    As of version 4.0.0, roxygen2 will never overwrite a file it didn't create. It does this by labelling every file it creates with a comment: “Generated by roxygen2 (version): do not edit by hand”.

    - + + + +