reprompt(object, infile = NULL, Rdtext = NULL, final = TRUE,
type = NULL, package = NULL, methods = NULL, verbose = TRUE,
filename = NULL, sec_copy = TRUE, ...)promptMethods, see Details.TRUE print messages on the screen.TRUE copy Rd contents of unchanged sections
in the result, see Details.reprompt is with one argument, as in
reprompt(infile = "./Rdpack/man/reprompt.Rd")
reprompt(reprompt)
reprompt("reprompt")
reprompt updates the requested documentation and writes the new
Rd file in the current working directory. When argument infile
is used, the descriptions of all objects described in the input file
are updated. When an object or its name is given, reprompt
looks first for installed documentation and processes it in the same
way as in the case of infile. If there is no documentation for
the object, reprompt creates a skeleton Rd file similar to the
one produced by the base R functions of the prompt family.
For S4 methods and classes the argument "package" is often needed to
restrict the output to methods defined in the package of interest.
reprompt("myfun-methods")
reprompt("[<--methods", package = "mypackage") # or
reprompt("[<-", type = "methods", package = "mypackage")
reprompt("myclass", type = "class", package = "mypackage") # or
reprompt("myclass-class", package = "mypackage")
For "myfun" above the "package" argument may not matter but for the
replacement method it almost certainly will.
Below are the details.
Typically, only one of object, infile, and Rdtext
is supplied. Warning messages are issued if this is not the case.
The object must have been made available by the time when
reprompt() is issued. If the object is in a package this is
typically achieved by a library() command.
object may be a function or a name, as accepted by the ?
operator. If it has the form "name-class" and "name-methods" a
documentation shell for class "name" or the methods for generic function
"name" will be examined/created. Alternatively, argument type
may be set to "class" or "methods" to achieve the same effect.
infile specifies a documentation file to be updated. If it
contains the documentation for one or more functions, reprompt
examines their usage statements and updates them if they have
changed. It also adds arguments to the "arguments" section if not all
arguments in the usage statements have entries there. If infile
describes the methods of a function or a class, the checks made are as
appropriate for them. For example, new methods and/or slots are added
to the corresponding sections.
Rdtext is similar to infile but the Rd content is taken
from a character vector.
If Rd content is supplied by infile or Rdtext,
reprompt uses it as a basis for comparison. Otherwise it tries
to find installed documentation for the object or topic requested.
If that fails, it resorts to one of the promptXXX functions to
generate a documentation shell. If that also fails, the requested
object or topic does not exist.
If the above succeeds, the function examines the current definition of
the requested object(s), methods, or class and amends the
documentation with any additional items it finds.
For Rd objects describing one or more functions, the usage expressions
are checked and replaced, if changed. Arguments appearing in one or
more usage expressions and missing from section "Arguments" are
amended to it with content "Describe ..." and a message is
printed. Arguments no longer in the usage statements are NOT removed
but a message is issued to alert the user. Alias sections are inserted
for any functions with "usage" but without "alias" section.
Currently reprompt functionality is not implemented for topic
"package" but if object has the form "name-package" (or the
equivalent with argument topic) and there is no documentation
for package?name, reprompt calls
promptPackageSexpr to create the required shell.
Note that the shell produced by promptPackageSexpr does not
need `reprompting' since the automatically generated information is
included by sec_copy is TRUE, reprompt will,
effectively, copy the contents of (some) unchanged sections, thus
ensuring that they are exactly the same as in the original.
In general, if an Rd object is obtained by parsing an Rd file, then
converting the object back to the Rd format may not reproduce the
original file exactly (some escape sequences may change). Even though
the new version should be functionally equivalent to the original,
this may not be desirable. For example, if such changes creep into
the Details section (which reprompt never changes) the user may
be annoyed or worried. Notice that this is not really a cause of
concern. Moreover, once you replace the old file with the one
one produced by reprompt, it will not change again.filename is a character string or NULL, the name of
the file to which the updated shell was written.
Otherwise, the text is returned as a character vector.reprompt are similar to prompt, with some
additions. As in prompt, filename specifies the output
file. In reprompt a new argument, infile, specifies the
input file containing the Rd source.
When reprompt is used to update sources of Rd documentation for
a package, it is best to supply the original Rd file in argument
infile. Otherwise, if the original Rd file contains
reprompt may not be able to recover the
original Rd content from the installed documentation. Also, the fields
(e.g. the keywords) in the installed documentation may not be were you
expect them to be. (This may be addressed in a future revision.)
A common error when supplying a file name for reprompt is to
forget to name the argument,
e.g. reprompt(infile="./Rdpack/man/reprompt.Rd"). Otherwise the
argument is taken to be the name of a function.
Currently a convenience convention is that if infile is missing
and object is a character string ending in ".Rd" and containing
a forward slash (i.e. it looks like Rd file in a directory), then it
is taken to be infile. However, this feature should not be
relied upon as it may be withdrawn since it is dubious and only
partially solves the problem with forgetting the name of the argument.
While reprompt adds new items to the documentation, it never
removes existing content. It only issues a suggestion to remove an
item, if it does not seem necessary any more (e.g. a removed argument
from a function definition).
reprompt handles usage statements for S3 and S4 methods
introduced with any of the macros reprompt to recreate the
usage section (e.g. to reformat long lines), invalidate the usage of
one of the described functions by removing an argument from its usage
expression. Currently the usage section is recreated completely if
the usage of any of the described functions has changed. Manual
formatting may be lost in such cases.
Todo: add an S3class argument (or equivalent) to allow specification
of S3 methods for reprompt. Note that S3 methods present in
usage statements are already processed. Also, giving the full name of
an S3 method as fun.class works, as well
(e.g. reprompt(predict.lm)).