flatdoc {mvbutils}R Documentation

Flat-format documentation

Description

flatdoc lets you edit plain-text documentation in the same file as your function definition. The documentation can be completely informal, or can be close to the standard on-screen appearance of R help files (and if so can be converted to actual Rd files by doc2Rd). This can be useful for your own notes, for informal distribution, and for formal distribution when you are trying to avoid managing dozens of separate source and documentation files.

Usage

# ALWAYS use it like this:
# structure( function( ...) {body},
# doc=flatdoc( EOF="<<end of doc>>"))
# plaintext doco goes here...
# NEVER use it like this:
flatdoc( EOF="<<end of doc>>")

Arguments

EOF character string showing when plain text ends, as in readlines.mvb
body replace with your function code
... replace with your function arg list

Details

A combined function-and-documentation text file should contain your function code wrapped in a structure( construct, followed by a line like this:

, doc=flatdoc())

The rest of the file is plain-text documentation, which will be formatted and shown by dochelp when help or ? is called. The documentation can be very informal, but if you follow some guidelines you will be able to convert it automatically to an Rd-format file by calling doc2Rd. There are no escape characters, so a single backslash "\" really means a single backslash.

When such a file is read in using source.mvb, the flatdoc call will cause the rest of the file to be read in as plain text, and assigned to the doc attribute of the function. Documentation can be terminated with this line:

<<end of doc>>

The above line will causes source.mvb to revert to normal statement processing mode for the rest of the file. Note that vanilla source will not respect flatdoc; you do need to use source.mvb.

Files in this format can be produced by write.sourceable.function, or by hand. The fixr editing system automatically outputs and inputs flatdoc format for functions with flat-format documentation.

On some text editors, you can modify syntax highlighting so that the "start of comment block" marker is set to the string "doc=flatdoc(".

It's possible to use flatdoc to read in more than one free-format text attribute. The EOF argument can be used to distinguish one block of free text from the next.

flatdoc should never be called from the command line; it should only appear in text files designed for source.mvb.

The fixr editor interface automatically uses the flatdoc approach to allow editing of source code and plain-text documentation in the same file. If you use a different editor interface, but like the idea of using flatdoc-style documentation, then you will need to:

Value

Character vector of class docattr, as read from the current.source() (qv) connection.

Note

You can also write combined code-and-documentation functions whose documentation merely refers to another function, like an alias in an Rd file. To refer to documentation stored with a function x, instead of setting doc to flatdoc() at the end of your structure(...) construct, set doc to list("x"). The referencing can be several layers deep; the documentation of x can refer to y, whose documentation refers to z, whose documentation is actually flatdoc()-style.

If you are writing documentation for a group of functions together, you only need to flatdoc one of them, say myfun1. Informal help will work if you modify the others to e.g.

myfun2 <- structure( function(...) { whatever}, doc=list("myfun1"))

If you are writing with doc2Rd in mind and a number of such functions are to be grouped together, e.g. a group of "internal" functions in preparation for formal package release, you may find make.usage.section and make.arguments.section helpful.

Author(s)

Mark Bravington

See Also

source.mvb, doc2Rd, dochelp, write.sourceable.function, make.usage.section,

make.arguments.section, fixr, the demo in "flatdoc.demo.R"

Examples

## Not run: 
## Put everything before the next comment into a text file <<your filename>>
structure( function( x) {
  x*x
}
,doc=flatdoc("<<end of doc>>"))
Here is some informal documentation for the "SQUARE" function
<<end of doc>>
## Now try SQUARE <- source.mvb( <<your filename>>); ?SQUARE
## Put everything before the next comment into a text file
myfun <- structure( function(...) {}
,  att1=flatdoc( EOF="<<end of part 1>>")
,  att2=flatdoc( EOF="<<end of part 2>>"))
This goes into "att1"
<<end of part 1>>
and this goes into "att2"
<<end of part 2>>
## Now "source.mvb" that file, to create "myfun"
cat( attr( myfun, "att1")) # This goes into "att1"
cat( attr( myfun, "att2")) # This goes into "att2"
## End(Not run)

[Package mvbutils version 2.2.0 Index]