R: Generate usage text for functions and methods

promptUsage {Rdpack} | R Documentation

## Generate usage text for functions and methods

### Description

Generates usage text for a function, S3 method or S4 method. The text is suitably formatted for inclusion in the usage section of Rd documentation.

### Usage

    get_usage(object, name = NULL, force.function = FALSE, ...,
              S3class = "", S4sig = "", infix = FALSE, fu = TRUE,
              out.format = "text")

    promptUsage(..., usage)

### Arguments

`object` | a function object or a character name of one, can be anonymous function.
`name` | the name of a function, a string.
`force.function` | enforce looking for a function.
`S3class` | the S3 class of the function, a character vector.
`out.format` | if "`text`", return the result as a character vector.
`S4sig` | (the signature of an S4 method, as used in Rd macro `\S4method`).
`infix` | if TRUE the function is an infix operator.
`fu` | if TRUE the object is a function, otherwise it is something else (e.g. a variable or a constant like `pi` and `Inf`).
`usage` | an usage object, see Details.
`...` | for `promptUsage`, arguments to be passed on to `get_usage`; for `get_usage`, currently not used.

### Details

`get_usage()` takes a function object, or the name of one, and creates text suitable for inclusion in the usage section of Rd documentation. The usage is generated from the function object. When in interactive R session, use `cat()` to print the result for copying and pasting into Rd documentation or saving to a file (otherwise, if the usage text contains backslashes, they may appear duplicated). Long text is wrapped on two or more lines. For example,

    cat(get_usage(lm))
    ##: lm(formula, data, subset, weights, na.action, method = "qr",
    ##:    model = TRUE, x = FALSE, y = FALSE, qr = TRUE, singular.ok = TRUE,
    ##:    contrasts = NULL, offset, \dots)

Argument `"name"` can be used to specify a print name for the function. This is most often needed for S3 methods. Compare

    cat(get_usage(summary.lm))
    ##: summary.lm(object, correlation = FALSE, symbolic.cor = FALSE, \dots)

and

    cat(get_usage(summary.lm, name = "summary"))
    ##: summary(object, correlation = FALSE, symbolic.cor = FALSE, \dots)

The call is just `summary()` in the latter. This fairly reflects the fact that S3 methods are normally called via the generic, but adding some explanatory text around the command is usually a good idea. For programmatically generated usage sections in help pages, argument `S3class` can be used to get the standard Rd markup for S3 methods.

    cat(get_usage(summary.lm, "summary", S3class = "lm"))
    ##: \method{summary}{lm}(object, correlation = FALSE, symbolic.cor = FALSE, \dots)

(Note that `\method` can only be used in Usage sections.)

When `object` is an anonymous function, argument `name` is compulsory. For example, `cat( get_usage(function(x = 3, y = "a"){}, "f") )` `##: f(x = 3, y = "a")`

`get_usage()` can also be used to insert dynamically signatures of functions located in other objects, such as environments and lists, see the examples.

If a function is used as an infix operator, set `infix = TRUE`.

    get_usage("+", infix = TRUE)
    ##: [1] "e1 + e2"
    get_usage("%in%", infix = TRUE)
    ##: [1] "x %in% table"

The name of the operator may be in a variable:

    op <- "+"
    get_usage(op, infix = TRUE)
    ##: [1] "e1 + e2"

Backticks are ok, as well,

    get_usage(`+`, infix = TRUE)
    ##: [1] "e1 + e2"

But if a backticked operator is in a variable, surprise springs:

    op <- `+`
    get_usage(op, infix = TRUE)
    ##: [1] "e1 op e2"

In this case, don't use backticks or, if you must, evaluate the argument:

    op <- `+`
    get_usage(eval(op), name = "+", infix = TRUE)
    ##: [1] "e1 + e2"

`promptUsage()` is mostly for internal use. It is like `get_usage()` with an additional argument, `usage`, used to pass a specially parsed argument list of class `"f_usage"`, produced by other functions in Rdpack. In particular it could have been generated by a previous call to `get_usage()`.

### Value

a character string or an object of S3 class "`f_usage`", see `pairlist2f_usage1` for its format.

### Note

For an S3 or S4 generic, use the name of the function, not the object, see the examples.

These functions are for usage descriptions as they appear in the "usage" section of Rd files. Descriptions of S4 methods for "Methods" sections are dealt with by other functions.

### Author(s)

Georgi N. Boshnakov

### See Also

`parse_pairlist`

### Examples

    u <- get_usage(lm)    # a long usage text
    cat(u)

    # if there are additional arguments in S3 methods,
    # use names of the functions, not the objects, e.g.
    get_usage("droplevels", S3class = "data.frame")
    get_usage(name = "droplevels", S3class = "data.frame")
    # (both give "\method{droplevels}{data.frame}(x, except = NULL, \dots)")

    # but this gives the args of the generic:  "\method{droplevels}{data.frame}(x, \dots)"
    get_usage(droplevels, S3class = "data.frame")

    ## a list containing some functions
    summaries <- list(xbar = function(x) mean(x), rho = function(x, y) cor(x,y))
    get_usage(summaries$xbar, name = "xbar")
    get_usage(summaries$rho, name = "rho")

    ## functions in an environment
    esummaries <- list2env(summaries)
    get_usage(esummaries$xbar, name = "xbar")
    get_usage(esummaries$rho, name = "rho")

[Package Rdpack version 0.10-1 Index]