structure( function( x, ...) {
  # just a comment
}
,doc=flatdoc( EOF='<<end of doc>>'))
some.functions package:mypack
sample.fun
another.fun

Showing doc2Rd documentation


DESCRIPTION

These functions exist solely to show what a 'doc2Rd'-ready file should look like. See DETAILS for details. Compare this file with the result of running it through 'doc2Rd'-- see the EXAMPLES section in the latter. This file is a bit old, certainly pre-R 2.10, and may be superceded by the help for 'doc2Rd'. 


USAGE

# USAGE is often not useful. Putting in extensive comments can help, e.g.:

# Don't use it like this
sample.fun( x, ...)

# ... use it like this instead: 
# sample.fun( quote(), a=25, b=37)

another.fun( y, z)


ARGUMENTS

 x: An argument. Note the space at the start of the line. Quotes are optional on LHS of the colon.
 ...: Whatever you like
 y, z: Another argument, which can refer to a 'code(fragment)'
 
You can also include general text in this section, by not starting the line with a space. Note that lines shouldn't be broken, unless you want a new paragraph.


VALUE

Often, people just put general text here; but you can itemize with a starting space, as per ARGUMENTS. For example, if 'sample.fun' returns a two-element list, you might include this:

 first.el: The first thing in the list
 second.el: The second thing in the list


DETAILS

There are no escaped characters, so e.g. a backslash "\" will appear in all flavours of help just as you wrote it in the original plain text. Special Rd fields are automatically generated by single quotes, e.g. 'paste(43,27)'. To refer to a package, use this phrasing: package 'base', or the 'base' package. To put in a link, use this phrasing: see 'paste'. Or this: 'paste' (qv). If the function/helpfile you're linking to is in your own package, the link will be generated automatically with no need for "see" or "qv". To cross-reference a section, such as USAGE (qv)-- well, that's exactly how you do it.

Email addresses, such as <mickey.mouse@ga.ga.ga>, and URLs, such as <http://cran.r-project.org>, ought to work, too.

You can also put in bullet-point lists, like this:

 - first bullet point
 - second bullet point
 
Bullet-point lists don't work inside EXAMPLES or USAGE. You get exactly what you type in those sections, in code-style font.

Here's an equation which will show nicely after Rd-conversion *and* show OK as text in informal help:

%\deqn{p(x) = \frac{\lambda^x e^{-\lambda}}{x!}}{%
%p(x) = lambda^x exp(-lambda)/x!}
%#ifdef flub
p(x) = lambda^x exp(-lambda)/x!
%#endif

Here's some phrases which were extraordinarily hard to display using Rd pre-2.10 (there are different tricky ones post-2.10):

a\b
a{{b}}
\code{a}

and now as a multi-line code fragment:
%%#
a\b
a{{b}}
\code{a}


EXAMPLES

sample.fun( 3) # the result
cat( "Single 'quotes' OK in USAGE, EXAMPLES, and multi-line code blocks")


USER.DEFINED.SECTION

This will appear as \section{User defined section} in the Rd file. It behaves like DETAILS or DSCRIPTION, so in particular you can have bullet lists...

 * ...with one or more elements
 

AUTHOR

An optional field, as is references.

The next section is SEE.ALSO not SEE ALSO-- note no spaces in section titles. Links are generated automatically in SEE.ALSO, without needing the "see..." or "...(qv)" contrivance.

In the final section, KEYWORDS, entries are separated by commas, semicolons, and/or line breaks. Check the "KEYWORDS.db" file in the R distribution for legal entries.


SEE.ALSO

'paste', package 'my.other.package', R-News 6/14, not quoted; 'nolink(here)'


KEYWORDS
 IO; documentation
 
<<end of doc>>

