rd_roclet: Roclet: make Rd files.

Description

This roclet is the workhorse of roxygen, producing the Rd files that document that functions in your package.

Usage

rd_roclet()

Arguments

Required tags

As well as a title and description, extracted from the first sentence and first paragraph respectively, all functions must have the following tags:

@param name description: Document a parameter. Documentation is required for every parameter.
@inheritParams source_function: Alternatively, you can inherit parameter description from another 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, function, or another package package::function.
@method generic class: Required if your function is an S3 method. This helps R to distinguish between (e.g.) t.test and the t method for the test class.

Optional tags that add extra information

Valid tags for rd_roclet are:

@examples R code...: Highly recommended: example code that demonstrates how to use your function. Use \dontrun to tag code that should not automatically be run.
@example path/relative/to/packge/root: Instead of including examples directly in the documentation, you can include them as separate files, and use the @example tag to insert them into the documentation.
@return: Used to document the object returned by the function. For lists, use the \item{name a}{description a} describe each component of the list
@author authors...: A free text string describing the authors of the function. This is typically only necessary if the author is not the same as the package author.
@note contents: Create a note section containing additional information.
@section Name: contents: Use to add to an arbitrary section to the documentation. The name of the section will be the content before the first colon, and the contents will be everything after the colon.
@keywords keyword1 keyword2 ...: Keywords are optional, but if present, must be taken from the list in file.path(R.home(), "doc/KEYWORDS"). Use the internal keyword for functions that should not appear in the main function listing.

Optional tags for cross-referencing

@aliases space separated aliases: Add additional aliases, through which the user can find the documentation with ?. The topic name is always included in the list of aliases.
@concepts space separated concepts: Similar to @aliases but for help.search
@references free text reference: Pointers to the literature related to this object.
@seealso Text with \code{\link{function}}: Pointers to related R objects, and why you might be interested in them.
@family family name: Automatically adds see-also cross-references between all functions in a family. A function can belong to multiple families.

Template tags

Templates make it possible to substantially reduce documentation duplication. A template is an R file in the man-roxygen/ directory. It is processed with brew and then inserted into the roxygen block. You can run any R code with brew; you can insert template variables with <%= varname %>.

@template templateName: Insert named template in current location.
@templateVar varname value: Set up variables for template use.

Limitations:

Templates are not parsed recursively, so you can not include templates from within other templates.
Templates must be composed of complete tags - becuase all roxygen tags are current block tags, they can not be used for inline insertions.

Optional tags that override defaults

These tags all override the default values that roxygen guess from inspecting the source code.

@rdname filename: Overrides the output file name (without extension). This is useful if your function has a name that is not a valid filename (e.g. [[<-), or you want to merge documentation for multiple function into a single file.
@title Topic title: Specify the topic title, which by by default is taken from the first sentence of the roxygen block.
@usage usage_string: Override the default usage string. You should not need to use this tag - if you are trying to document multiple functions in the same topic, use @rdname.

Tags for non-functions

These tags are useful when documenting things that aren't functions, datasets and packages.

@name topicname: Override the default topic name, which is taken by default from the object that is assigned to in the code immediately following the roxygen block. This tag is useful when documenting datasets, and other non-function elements.
@docType type: Type of object being documented. Useful values are data and package. Package doc type will automatically add a package- alias if needed.
@format description: A textual description of the format of the object.
@source text: The original source of the data.
@slot name description: Describe the slots of an S4 class in a standard way. Slots will be listed in their own section.

Details

This roclet also automatically runs checkRd on all generated Rd files so that you know as early as possible if there's a problem.

Examples

Run this code

roclet <- rd_roclet()
## Not run: roc_proc(roclet, "example.R")
## Not run: roc_out(roclet, "example.R", ".")

Run the code above in your browser using DataLab