man-other.Rmd

# Other documentation

```{r, echo = FALSE}
source("common.R")
status("drafting")
```

## Introduction

## Documenting packages {#man-packages}

You can use roxygen to provide a help page for your package as a whole.
This is accessed with `package?foo`, and can be used to describe the most important components of your package.
It's a useful supplement to vignettes, as described in the next chapter.

There's no object that corresponds to a package, so you need to document `NULL`, and then manually label it with `@docType package` and `@name <package-name>`.
This is also an excellent place to use the `@section` tag to divide up page into useful categories.

```{r}
#' foo: A package for computating the notorious bar statistic
#'
#' The foo package provides three categories of important functions:
#' foo, bar and baz.
#' 
#' @section Foo functions:
#' The foo functions ...
#'
#' @docType package
#' @name foo
NULL
```

I usually put this documentation in a file called `<package-name>.R`.
It's also a good place to put the package level import statements that you'll learn about in @sec-imports.

## Documenting classes, generics and methods {#man-classes}

It's relatively straightforward to document classes, generics and methods.
The details vary based on the object system you're using.
The following sections give the details for the S3, S4 and RC object systems.

### S3 {#man-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()`.
But if your method is more complicated or includes additional arguments, you should document it so people know how it works.
In base R, you can see examples of 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 version 3.0.0 onward, this is no longer needed as 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 {#man-s4}

Document **S4 classes** by adding a roxygen block before `setClass()`.
Use `@slot` to document the slots of the class in the same way you use `@param` to describe the parameters of a function.
Here's a simple example:

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

S4 **generics** are also functions, so document them as such.
S4 **methods** are a little more complicated, however.
Unlike S3, all S4 methods must be documented.
You document them like a regular function, but you probably don't want each method to have its own documentation page.
Instead, put the method documentation in one of 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 have written both the generic and the method.

-   In its own file.
    Most appropriate if the method is complex, or if you've written the method but not the class or generic.

Use either `@rdname` or `@describeIn` to control where method documentation goes.

Another consideration is that S4 code often needs to run in a certain order.
For example, to define the method `setMethod("foo", c("bar", "baz"), ...)` you must already have created the `foo` generic and the two classes.
By default, R code is loaded in alphabetical order, but that won't always work for your situation.
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:

```{r, eval = FALSE}
#' @include class-a.R
setClass("B", contains = "A")
```

Often, it's easiest to put this at the top of the file.
To make it clear that this tag applies to the whole file, and not a specific object, document `NULL`.

```{r, eval = FALSE}
#' @include foo.R bar.R baz.R
NULL

setMethod("foo", c("bar", "baz"), ...)
```

Roxygen uses the `@include` tags to compute a topological sort which ensures that dependencies are loaded before they're needed.
It then sets the `Collate` field in `DESCRIPTION`, which overrides the default alphabetic ordering.
A simpler alternative to `@include` is to define all classes and methods in `aaa-classes.R` and `aaa-generics.R`, and rely on these coming first since they're in alphabetical order.
The main disadvantage is that you can't organise components into files as naturally as you might want.

Older versions of roxygen2 required explicit `@usage`, `@alias` and `@docType` tags for documenting S4 objects.
However, as of version 3.0.0, roxygen2 generates the correct values automatically so you no longer need to use them.
If you're upgrading from an old version, you can delete these tags.

### RC {#man-rc}

Reference classes are different to S3 and S4 because methods are associated with classes, not generics.
RC also has a special convention for documenting methods: the **docstring**.
The docstring is a string placed inside the definition of the method which briefly describes what it does.
This makes documenting RC simpler than S4 because you only need one roxygen block per class.

```{r}
#' 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.
Also note the use of `@field` instead of `@slot`.