mvbutils (version 2.8.232)

add.flatdoc.to: Skeletal flat-format documentation

Description

You very likely don't need to read this--- add.flatdoc.to is usually called automatically for you, by fixr( ..., new.doc=TRUE). It adds skeleton flat-format documentation to a function, suitable for conversion to Rd-format using doc2Rd. The result should pass RCMD CHECK (but won't be much use until you actually edit the documentation).

Usage

# See *Examples* for practical usage
add.flatdoc.to(x, char.x = NULL, pkg=NULL, env=NULL, convert.to.source=FALSE)

Arguments

x

unquoted function name, sought in parent.frame() unless pkg is set

char.x

[string] function name

pkg

[string] name of maintained package where x lives (optional)

env

[environment] where to get x from; defaults to caller unless pkg is set.

convert.to.source

[logical] if TRUE and x has a "srcref" attribute, the latter is converted to a source attribute. This ensures that fixr will write the function correctly to the temporary file used by your text editor. Default is FALSE for historical reasons.

Value

A function with attribute doc containing the flat-format documentation.

Details

You don't have to write Rd-compatible documentation from the outset. You can write documentation that's as free-form as you wish, and there's no need to use add.flatdoc.to to do it-- you can write the doco directly in your text editor provided that you can source the resultant melange OK (see fixr). I find add.flatdoc.to useful, though, because I can never remember the headings or mild layout conventions of doc2Rd and Rd-format itself.

See Also

flatdoc, fixr, doc2Rd

Examples

# NOT RUN {
myfun <- function( ...) ...
myfun <- add.flatdoc.to( myfun)
# 'fixr( myfun)' will now allow editing of code & doco together
# Or, in a maintained package:
# ..mypack$myfun <<- add.flatdoc.to( myfun, pkg='mypack')
# }