Rdpack (version 0.4-20)

reprompt: Update the documentation of a topic

Description

Examine the documentation of functions, methods or classes and update it with additional arguments, methods or slots, as appropriate. This is an extention of the promptXXX() family of functions.

Usage

reprompt(object, infile = NULL, Rdtext = NULL, final = TRUE, type = NULL, package = NULL, methods = NULL, verbose = TRUE, filename = NULL, sec_copy = TRUE, ...)

Arguments

object

the object whose documentation is to be updated, such as a string, a function, a help topic, a parsed Rd object, see `Details'.

infile

a file name containing Rd documentation, see `Details'.

Rdtext

a character string with Rd formatted text, see `Details'.

final

logical, see `Details'.

type

type of topic, e.g. "methods", see `Details'.

package

package name; document only objects defined in this package.

methods

used for documentation of S4 methods only, syntax is as the corresponding argument in promptMethods, see Details.

verbose

if TRUE print messages on the screen.

filename

name of the file for the generated Rd content.

...

currently not used

sec_copy

if TRUE copy Rd contents of unchanged sections in the result, see Details.

Value

if 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.

Details

The typical use of 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 \Sexpr, not literal strings.

If argument 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.

Examples

# note: usage of reprompt() is simple.
#       the examples below are bulky because they
#       simulate various usage scenarios.
#
# change to a temporary directory to avoid clogging up user's
cur_wd <- getwd()
setwd(tempdir())

# as for prompt() the default to save in current dir as "seq.Rd".
# the argument here is a function, reprompt finds its doc. and
# updates all objects described along with `seq'.
# (In this case there is nothing to update, we have not changed `seq'.)

fnseq <- reprompt(seq)

# let's parse the saved Rd file
rdoseq <- parse_Rd(fnseq)

# replace usage statements with wrong ones for illustration.
dummy_usage <- char2Rdpiece(paste("seq()", "\\method{seq}{default}()",
                   "seq.int()", "seq_along()", "seq_len()", sep="\n"),
                   "usage")
rdoseq_dummy <- Rdo_replace_section(rdoseq, dummy_usage)
Rdo_show(rdoseq_dummy)  # wrong usage

reprompt(rdoseq_dummy, file = "seqA.Rd")
Rdo_show(parse_Rd("seqA.Rd"))  # usage ok now

myseq <- function(from, to, x){
        if(to < 0) seq(from=from, to=length(x)+to) else seq(from, to)}

# add a description of  sequence()
rdo2 <- Rdo_modify_simple(rdoseq, "myseq()", "usage")

reprompt(rdo2, file = "seqB.Rd")  # updates usage of myseq
Rdo_show(parse_Rd("seqB.Rd"))     # and add an entry for 'x' in 'arguments'




# as for prompt() the default is to save in current dir as "seq.Rd".
fnseq <- reprompt(seq)
rdoseq <- parse_Rd(fnseq)   # parse fnseq to see the result.
Rdo_show(rdoseq)

reprompt(infile = "seq.Rd", filename = "seq2.Rd")
reprompt(infile = "seq2.Rd", filename = "seq3.Rd")

# Rd objects for installed help may need some tidying for human editing.
hseq_inst <- help("seq")
rdo <- utils:::.getHelpFile(hseq_inst)
rdo
rdo <- Rdpack:::.Rd_tidy(rdo)          # tidy up (e.g. insert new lines
                                       #          for human readers)

reprompt(rdo) # same as rdoseq;



unlink("seq.Rd")         # remove temporary files
unlink("seq2.Rd")
unlink("seq3.Rd")
unlink("seqA.Rd")
unlink("seqB.Rd")

setwd(cur_wd)            # restore user's working directory