extract.xxx.chunks: Extract documentation from a function

Description Usage Arguments Details Value Note Author(s)

View source: R/parsers.R

Description

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

Usage

1
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:

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<c3><bc>ller [aut], R Core Team [ctb, cph]


inlinedocs documentation built on May 31, 2017, 1:56 a.m.

Search within the inlinedocs package
Search all R packages, documentation and source code