R: Produce Prototype of an R Documentation File

prompt {utils} | R Documentation

## Produce Prototype of an R Documentation File

### Description

Facilitate the constructing of files documenting R objects.

### Usage

    prompt(object, filename = NULL, name = NULL, ...)

    ## Default S3 method:
    prompt(object, filename = NULL, name = NULL,
           force.function = FALSE, ...)

    ## S3 method for class '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.

### 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.

### 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.

### Note

The documentation file produced by `prompt.data.frame` does not have the same format as many of the data frame documentation files in the base package. We are trying to settle on a preferred format for the documentation.

### Author(s)

Douglas Bates for `prompt.data.frame`

### 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

    require(graphics)

    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)

    ## End(Not run)

[Package utils version 4.0.5 Index]