extract.xxx.chunks: Extract documentation from a function

In inlinedocs: Convert Inline Comments to 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 <[e-mail]> [aut, cre], Keith Ponting [aut], Thomas Wutzler [aut], Philippe Grosjean [aut], Markus Müller [aut], R Core Team [ctb, cph]

inlinedocs documentation built on Oct. 19, 2023, 1:06 a.m.