utils (version 3.6.0)

prompt: Produce Prototype of an R Documentation File

Description

Facilitate the constructing of files documenting R objects.

Usage

prompt(object, filename = NULL, name = NULL, …)
# S3 method for default
prompt(object, filename = NULL, name = NULL,
       force.function = FALSE, …)
# S3 method for data.frame
prompt(object, filename = NULL, name = NULL, …)
promptImport(object, filename = NULL, name = NULL, 
	importedFrom = NULL, importPage = name, ...)

Arguments

object

an R object, typically a function for the default method. Can be missing when name is specified.

filename

usually, a connection or a character string giving the name of the file to which the documentation shell should be written. The default corresponds to a file whose name is name followed by ".Rd". Can also be NA (see below).

name

a character string specifying the name of the object.

force.function

a logical. If TRUE, treat object as function in any case.

…

further arguments passed to or from other methods.

importedFrom

a character string naming the package from which object was imported. Defaults to the environment of object if object is a function.

importPage

a character string naming the help page in the package from which object was imported.

Value

If filename is NA, a list-style representation of the documentation shell. Otherwise, the name of the file written to is returned invisibly.

Warning

The default filename may not be a valid filename under limited file systems (e.g., those on Windows).

Currently, calling prompt on a non-function object assumes that the object is in fact a data set and hence documents it as such. This may change in future versions of R. Use promptData to create documentation skeletons for data sets.

Details

Unless filename is NA, a documentation shell for object is written to the file specified by filename, and a message about this is given. For function objects, this shell contains the proper function and argument names. R documentation files thus created still need to be edited and moved into the man subdirectory of the package containing the object to be documented.

If filename is NA, a list-style representation of the documentation shell is created and returned. Writing the shell to a file amounts to cat(unlist(x), file = filename, sep = "\n"), where x is the list-style representation.

When prompt is used in for loops or scripts, the explicit name specification will be useful.

The importPage argument for promptImport needs to give the base of the name of the help file of the original help page. For example, the approx function is documented in approxfun.Rd in the stats package, so if it were imported and re-exported it should have importPage = "approxfun". Objects that are imported from other packages are not normally documented unless re-exported.

References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.

See Also

promptData, help and the chapter on “Writing R documentation” in “Writing R Extensions” (see the doc/manual subdirectory of the R source tree).

For creation of many help pages (for a package), see package.skeleton.

To prompt the user for input, see readline.

Examples

# NOT RUN {
require(graphics)
# }
# NOT RUN {
prompt(plot.default)
prompt(interactive, force.function = TRUE)
unlink("plot.default.Rd")
unlink("interactive.Rd")

prompt(women) # data.frame
unlink("women.Rd")

prompt(sunspots) # non-data.frame data
unlink("sunspots.Rd")

# }
# NOT RUN {
## Create a help file for each function in the .GlobalEnv:
for(f in ls()) if(is.function(get(f))) prompt(name = f)
# }
# NOT RUN {
# }