| Documentation {methods} | R Documentation |
Special documentation can be supplied to describe the classes and methods that are created by the software in the methods package. Techniques to access this documentation and to create it in R help files are described here.
You can ask for on-line help for class definitions, for specific
methods for a generic function, and for general discussion of
methods for a generic function. These requests use the ?
operator (see help for a general description of
the operator). Of course, you are at the mercy of the implementer
as to whether there is any documentation on the corresponding
topics.
Documentation on a class uses the argument class on the left
of the ?, and the name of the class on the right; for
example,
class ? genericFunction
to ask for documentation on the class "genericFunction".
When you want documentation for the methods defined for a particular function, you can ask either for a general discussion of the methods or for documentation of a particular method (that is, the method that would be selected for a particular set of actual arguments).
Overall methods documentation is requested by
calling the ? operator with methods as the left-side
argument and the name of the function as the right-side argument. For
example,
methods ? initialize
asks for documentation on the methods for the initialize
function.
Asking for documentation on a particular method is done by giving a
function call expression as the right-hand argument to the "?"
operator. There are two forms, depending on whether you prefer to
give the class names for the arguments or expressions that you intend
to use in the actual call.
If you planned to evaluate a function call, say myFun(x, sqrt(wt))
and wanted to find out something about the method that would be used
for this call, put the call on the right of the "?" operator:
?myFun(x, sqrt(wt))
A method will be selected, as it would be for the call itself, and
documentation for that method will be requested. If myFun is
not a generic function, ordinary documentation for the function will
be requested.
If you know the actual classes for which you would like method
documentation, you can supply these explicitly in place of the
argument expressions. In the example above, if you want method
documentation for the first argument having class "maybeNumber"
and the second "logical", call the "?" operator, this
time with a left-side argument method, and with a function call
on the right using the class names as arguments:
method ? myFun("maybeNumber", "logical")
Once again, a method will be selected, this time corresponding to the specified classes, and method documentation will be requested. This version only works with generic functions.
The two forms each have advantages. The version with actual arguments
doesn't require you to figure out (or guess at) the classes of the
arguments.
On the other hand, evaluating the arguments may take some time,
depending on the example.
The version with class names does require you to pick classes, but
it's otherwise unambiguous. It has a subtler advantage, in that the
classes supplied may be virtual classes, in which case no actual
argument will have specifically this class. The class
"maybeNumber", for example, might be a class union (see the
example for setClassUnion).
In either form, methods will be selected as they would be in actual
computation, including use of inheritance and group generic
functions. See selectMethod for the details, since it is
the function used to find the appropriate method.
The on-line documentation for methods and classes uses some extensions to the R documentation format to implement the requests for class and method documentation described above. See the document Writing R Extensions for the available markup commands (you should have consulted this document already if you are at the stage of documenting your software).
In addition to the specific markup commands to be described, you can create an initial, overall file with a skeleton of documentation for the methods defined for a particular generic function:
promptMethods("myFun")
will create a file, ‘myFun-methods.Rd’ with a skeleton of
documentation for the methods defined for function myFun.
The output from promptMethods is suitable if you want to
describe all or most of the methods for the function in one file,
separate from the documentation of the generic function itself.
Once the file has been filled in and moved to the ‘man’
subdirectory of your source package, requests for methods
documentation will use that file, both for specific methods
documentation as described above, and for overall documentation
requested by
methods ? myFun
You are not required to use promptMethods, and if you do, you
may not want to use the entire file created:
If you want to document the methods in the file containing the
documentation for the generic function itself, you can
cut-and-paste to move the \alias lines and the
Methods section from the file created by
promptMethods to the existing file.
On the other hand, if these are auxiliary methods, and you only
want to document the added or modified software, you should strip
out all but the relevant \alias lines for the methods of
interest, and remove all but the corresponding \item
entries in the Methods section. Note that in this case you
will usually remove the first \alias line as well, since
that is the marker for general methods documentation on this
function (in the example, ‘\alias{myfun-methods}’).
If you simply want to direct documentation for one or more methods to a particular R documentation file, insert the appropriate alias.