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,
.Rdpack.e <- environment();Rdpack:::run_examples(quote({cat( get_usage(lm) )}), local = .Rdpack.e, Rdsection = "preformatted")
Argument "name"
can be used to specify a print name for the function.
This is most often needed for S3 methods. Compare
.Rdpack.e <- environment();Rdpack:::run_examples(quote({cat( get_usage(summary.lm) )}), local = .Rdpack.e, Rdsection = "preformatted")
and
.Rdpack.e <- environment();Rdpack:::run_examples(quote({cat( get_usage(summary.lm, name = "summary") )}), local = .Rdpack.e, Rdsection = "preformatted")
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.
.Rdpack.e <- environment();Rdpack:::run_examples(quote({cat( get_usage(summary.lm, "summary", S3class = "lm") )}), local = .Rdpack.e, Rdsection = "preformatted")
(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
.
.Rdpack.e <- environment();Rdpack:::run_examples(quote({get_usage("+", infix = TRUE); get_usage("%in%", infix = TRUE)}), local = .Rdpack.e, Rdsection = "preformatted")
The name of the operator may be in a variable:
.Rdpack.e <- environment();Rdpack:::run_examples(quote({op <- "+"; get_usage(op, infix = TRUE)}), local = .Rdpack.e, Rdsection = "preformatted")
Backticks are ok, as well,
.Rdpack.e <- environment();Rdpack:::run_examples(quote({get_usage(`+`, infix = TRUE)}), local = .Rdpack.e, Rdsection = "preformatted")
But if a backticked operator is in a variable, surprise springs:
.Rdpack.e <- environment();Rdpack:::run_examples(quote({op <- `+`; get_usage(op, infix = TRUE)}), local = .Rdpack.e, Rdsection = "preformatted")
In this case, don't use backticks or, if you must, evaluate the argument:
.Rdpack.e <- environment();Rdpack:::run_examples(quote({op <- `+`; get_usage(eval(op), name = "+", infix = TRUE)}), local = .Rdpack.e, Rdsection = "preformatted")
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()
.