Documentation            package:methods            R Documentation

Using and Creating On-line Documentation for Classes and
Methods

Description:

     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.

Getting documentation on classes and methods:

     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.

Writing Documentation for Methods:

     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.

