Get textual help on function or function arguments, or get a call tip
Source:R/describe_function.R
describe_function.RdTextual help on functions or their arguments is extracted for
text online help for a given function. By default, all arguments from the
online help are returned for describe_args(). If the file contains help for
several functions, one probably gets also some irrelevant information. Use of
'args' to limit result is strongly encouraged. args_tip() provides a
human-readable textual description of function arguments in a better way than
args() does. It is primarily intended for code tips in GUIs. call_tip()
has a similar purpose to show how some code could be completed.
describe_function(fun, package, lib.loc = NULL)
describe_args(fun, args = NULL, package = NULL, lib.loc = NULL)
args_tip(name, only.args = FALSE, width = getOption("width"))
call_tip(
code,
only.args = FALSE,
location = FALSE,
description = FALSE,
methods = FALSE,
width = getOption("width")
)
descFun(fun, package, lib.loc = NULL)
descArgs(fun, args = NULL, package = NULL, lib.loc = NULL)
argsTip(name, only.args = FALSE, width = getOption("width"))
callTip(
code,
only.args = FALSE,
location = FALSE,
description = FALSE,
methods = FALSE,
width = getOption("width")
)Arguments
- fun
A character string with the name of a function (several functions accepted too for
describe_function().- package
A character string with the name of the package that contains
fun, orNULLfor searching in all loaded packages.- lib.loc
A character vector of directory names of R libraries, or
NULL. The default value ofNULLcorresponds to all libraries currently known. If the default is used, the loaded packages are searched before the libraries.- args
Either
NULL(by default) to return the description of all arguments from the corresponding man page, or a character vector with names of the arguments to search for.- name
A string with the name of a function.
- only.args
Do we return only arguments of the function (
arg1, arg2 = TRUE, ...), or the full call, like (myfun(arg1, arg2 = TRUE, ...)).- width
Reformat the tip to fit to fit in that width, except if
width = NULL.- code
A fraction of R code ending with the name of a function, eventually followed by '('.
- location
If
TRUEthen the location (in which package the function resides) is appended to the calltip between square brackets.- description
If
TRUEthen a short description of the function is added to the call_tip (in fact, the title of the corresponding help page, if it exists).- methods
If
TRUEthen a short message indicating if this is a generic function and that lists, in this case, available methods.
Value
A string with the description of the function or of its arguments, or the calling syntax of the function, plus additional information depending on the flags used. If the man page is not found, a vector of empty strings is returned. Empty strings are also returned for arguments that are not found in the man page.
Note
args_tip() is supposed to display S3 and S4 methods, and primitives
adequately,... but this is not implemented yet in the current version! For
call_tip(), the use of methods = TRUE slows down the execution of the
function, especially for generic functions that have many methods like
print() or summary().
See also
Examples
describe_function("ls", "base")
#> [1] "List Objects"
describe_function("library", "base")
#> [1] "Loading/Attaching and Listing of Packages"
describe_function("descFun", "svMisc")
#> [1] "Get textual help on function or function arguments, or get a call tip"
describe_function("descArgs")
#> [1] "Get textual help on function or function arguments, or get a call tip"
describe_args("ls")
#> name
#> "which environment to use in listing the available objects.\n Defaults to the current environment. Although called\n name for back compatibility, in fact this argument can\n specify the environment in any form; see the Details section."
#> pos
#> "an alternative argument to name for specifying the\n environment as a position in the search list. Mostly there for\n back compatibility."
#> envir
#> "an alternative argument to name for specifying the\n environment. Mostly there for back compatibility."
#> all.names
#> "a logical value. If TRUE, all\n object names are returned. If FALSE, names which begin with a\n . are omitted."
#> pattern
#> "an optional regular expression. Only names\n matching pattern are returned. glob2rx can be\n used to convert wildcard patterns to regular expressions."
#> sorted
#> "logical indicating if the resulting\n character should be sorted alphabetically. Note that\n this is part of ls() may take most of the time."
describe_args("library", args = c("package", "pos"))
#> package
#> "the name of a package, given as a name or\n literal character string, or a character string, depending on\n whether character.only is FALSE (default) or\n TRUE."
#> pos
#> "the position on the search list at which to attach the\n loaded namespace. Can also be the name of a position on the current\n search list as given by search()."
args_tip("ls")
#> [1] "ls(name, pos = -1L, envir = as.environment(pos), all.names = FALSE, pattern,\n sorted = TRUE)"
call_tip("myvar <- lm(")
#> [1] "lm(formula, data, subset, weights, na.action, method = \"qr\", model = TRUE, x =\n FALSE, y = FALSE, qr = TRUE, singular.ok = TRUE, contrasts = NULL, offset,\n ...)"