R: Extract documentation from a function

extract.xxx.chunks {inlinedocs} | R Documentation

## Extract documentation from a function

### Description

Given source code of a function, return a list describing inline documentation in that source code.

### Usage

    extract.xxx.chunks(src, name.fun = "(unnamed function)", ...)

### Arguments

`src` | The source lines of the function to examine, as a character vector.
`name.fun` | The name of the function/chunk to use in warning messages.
`...` | ignored.

### Details

For simple functions/arguments, the argument may also be documented by appending `##<<` comments on the same line as the argument name. Mixing this mechanism with `###` comment lines for the same argument is likely to lead to confusion, as the `###` lines are processed first.

Additionally, consecutive sections of `##` comment lines beginning with `##`xxx`<<` (where xxx is one of the fields: `alias`, `details`, `keyword`, `references`, `author`, `note`, `seealso`, `value`, `title` or `description`) are accumulated and inserted in the relevant part of the .Rd file.

For `value`, `title`, `description` and function arguments, these append to any text from "prefix" (`^###` ) comment lines, irrespective of the order in the source.

When documenting S4 classes, documentation from `details` sections will appear under a section `Objects from the Class`. That section typically includes information about construction methods as well as other description of class objects (but note that the class Slots are documented in a separate section).

Each separate extra section appears as a new paragraph except that:

- empty sections (no matter how many lines) are ignored;

- `alias` and `keyword` sections have special rules;

- `description` should be brief, so all such sections are concatenated as one paragraph;

- `title` should be one line, so any extra `title` sections are concatenated as a single line with spaces separating the sections.

As a special case, the construct `##describe<<` causes similar processing to the main function arguments to be applied in order to construct a describe block within the documentation, for example to describe the members of a list. All subsequent "same line" `##<<` comments go into that block until terminated by a subsequent `##`xxx`<<` line.

Such regions may be nested, but not in such a way that the first element in a `describe` is another `describe`. Thus there must be at least one `##<<` comment between each pair of `##describe<<` comments.

When nested `describe` blocks are used, a comment-only line with `##end<<` terminates the current level only; any other valid `##`xxx`<<` line terminates all open describe blocks.

### Value

Named list of character strings extracted from comments. For each name N we will look for N{...} in the Rd file and replace it with the string in this list (implemented in modify.Rd.file).

### Note

`alias` extras are automatically split at new lines.

`keyword` extras are automatically split at white space, as all the valid keywords are single words.

The "value" section of a .Rd file is implicitly a describe block and `##``value``<<` acts accordingly. Therefore it automatically enables the describe block itemization (##<< after list entries).

### Author(s)

Toby Dylan Hocking <toby@sg.cs.titech.ac.jp> [aut, cre], Keith Ponting [aut], Thomas Wutzler [aut], Philippe Grosjean [aut], Markus Müller [aut], R Core Team [ctb, cph]

[Package inlinedocs version 2013.9.3 Index]