Generate usage text for functions and methods

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") )

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.

Author

Georgi N. Boshnakov

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.

Examples

u <- get_usage(lm)    # a long usage text
cat(u)
#> lm(formula, data, subset, weights, na.action, method = "qr", 
#>    model = TRUE, x = FALSE, y = FALSE, qr = TRUE, singular.ok = TRUE, 
#>    contrasts = NULL, offset, \dots)

# if there are additional arguments in S3 methods,
# use names of the functions, not the objects, e.g.
get_usage("droplevels", S3class = "data.frame")
#>                                                            droplevels 
#> "\\method{droplevels}{data.frame}(x, except = NULL, exclude, \\dots)" 
get_usage(name = "droplevels", S3class = "data.frame")
#>                                                            droplevels 
#> "\\method{droplevels}{data.frame}(x, except = NULL, exclude, \\dots)" 
# (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")
#>                                    droplevels 
#> "\\method{droplevels}{data.frame}(x, \\dots)" 

## 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")
#>      xbar 
#> "xbar(x)" 
get_usage(summaries$rho, name = "rho")
#>         rho 
#> "rho(x, y)" 

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