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
andkeyword
sections have special rules; -
description
should be brief, so all such sections are concatenated as one paragraph; -
title
should be one line, so any extratitle
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.hocking@r-project.org> [aut, cre], Keith Ponting [aut], Thomas Wutzler [aut], Philippe Grosjean [aut], Markus Müller [aut], R Core Team [ctb, cph]