SCM

SCM Repository

[inlinedocs] Annotation of /pkg/inlinedocs/man/extract.xxx.chunks.Rd
ViewVC logotype

Annotation of /pkg/inlinedocs/man/extract.xxx.chunks.Rd

Parent Directory Parent Directory | Revision Log Revision Log


Revision 305 - (view) (download) (as text)

1 : kmpont 213 \name{extract.xxx.chunks}
2 :     \alias{extract.xxx.chunks}
3 :     \title{Extract documentation from a function}
4 :     \description{Given source code of a function, return a list describing inline
5 :     documentation in that source code.}
6 :     \usage{
7 : tdhock 304 extract.xxx.chunks(src,
8 :     name.fun = "(unnamed function)",
9 :     ...)
10 : kmpont 213 }
11 :     \arguments{
12 :     \item{src}{The source lines of the function to examine, as a character
13 :     vector.}
14 :     \item{name.fun}{The name of the function/chunk to use in warning messages.}
15 :     \item{\dots}{ignored.}
16 :     }
17 :     \details{For simple functions/arguments, the argument may also be
18 :     documented by appending comments on the same line as the
19 :     argument name. Mixing this mechanism with comment lines for
20 :     the same argument is likely to lead to confusion, as the
21 :     lines are processed first.
22 :    
23 :     Additionally, consecutive sections of comment
24 :     lines beginning with \emph{xxx} (where
25 :     \emph{xxx} is one of the fields: \code{alias}, \code{details},
26 :     \code{keyword}, \code{references}, \code{author}, \code{note},
27 :     \code{seealso}, \code{value}, \code{title} or \code{description})
28 :     are accumulated and inserted in the relevant part of the .Rd
29 :     file.
30 :    
31 :     For \code{value}, \code{title}, \code{description} and function
32 :     arguments, these \emph{append} to any text from "prefix"
33 :     () comment lines, irrespective of the order in the
34 :     source.
35 :    
36 :     When documenting S4 classes, documentation from \code{details}
37 :     sections will appear under a section \code{Objects from the Class}. That
38 :     section typically includes information about construction methods
39 :     as well as other description of class objects (but note that the
40 :     class Slots are documented in a separate section).
41 :    
42 :     Each separate extra section appears as a new
43 :     paragraph except that: \itemize{\item empty sections (no
44 :     matter how many lines) are ignored;\item \code{alias} and
45 :     \code{keyword} sections have special rules;\item
46 :     \code{description} should be brief, so all such sections
47 :     are concatenated as one paragraph;\item \code{title} should
48 :     be one line, so any extra \code{title} sections are
49 :     concatenated as a single line with spaces separating the
50 :     sections.}
51 :    
52 :     As a special case, the construct \code{##describe<<} causes
53 :     similar processing to the main function arguments to be
54 :     applied in order to construct a describe block within the
55 :     documentation, for example to describe the members of a
56 :     list. All subsequent "same line" comments go into that
57 :     block until terminated by a subsequent \emph{xxx} line.
58 :    
59 :     Such regions may be nested, but not in such a way
60 :     that the first element in a \code{describe} is another \code{describe}.
61 :     Thus there must be at least one comment between each
62 :     pair of \code{##describe<<} comments.
63 :    
64 :     When nested \code{describe} blocks are used, a comment-only
65 :     line with \code{##end<<} terminates the current level only; any
66 :     other valid \emph{xxx} line terminates
67 :     all open describe blocks.}
68 :     \value{Named list of character strings extracted from comments. For each
69 :     name N we will look for N\{...\} in the Rd file and replace it
70 :     with the string in this list (implemented in modify.Rd.file).}
71 :    
72 : tdhock 291 \author{Inlinedocs development team
73 :     <inlinedocs-support@lists.r-forge.r-project.org>}
74 : kmpont 213 \note{\code{alias} extras are automatically split at new lines.
75 :    
76 :     \code{keyword} extras are automatically split at white space,
77 :     as all the valid keywords are single words.
78 :    
79 :     The "value" section of a .Rd file is implicitly a describe
80 :     block and \code{value} acts accordingly. Therefore
81 :     it automatically enables the describe block itemization (##<< after
82 :     list entries).}
83 :    
84 :    
85 :    
86 :    
87 :    
88 :     \keyword{documentation}
89 :     \keyword{utilities}

root@r-forge.r-project.org
ViewVC Help
Powered by ViewVC 1.0.0  
Thanks to:
Vienna University of Economics and Business Powered By FusionForge