Documenting ReferenceClass generators and their methods

reference_classes.md

ReferenceClass (RC) documentation

The problem

RC generators should be documented the same way S4 objects are documented. However, there is no convention to documenting RC methods.

Guidance that is available

Generator objects

The documentation of RC generator objects follows the general pattern of S4 classes. The sections or bits automatically generated (using promptClass) for an RC that I have written are:

1. Name
2. Document type
3. Aliases
4. Title
5. Description
6. Extends
7. Methods
8. References
9. Author
10. Note
11. See also
12. Examples
13. Keyword
14. Fields
15. Class-based methods

Of these sections, the two sections Methods and Class-based methods should be noted. The first automatically collates all the generics functions defined for the RC class I have developed. The other lists the defined RC methods and includes their signature.

RC methods

The official documentation states that Rd files are not used to document RC methods and but also the help that the $help(topic) output should be "brief". The former, taken together with the listing of RC methods using promptClass(), would suggest that the method should not be documented in the RC generator object's help file, except perhaps scantly. The latter would suggest that the method's docstring should be short as well. Given the explicit prohibition of Rd based method documentation, and the ambiguous prohibition on comprehensive docstring documentation, it may be best to ignore the latter.

Suggested solution

RC documentation should consist of:

1. Rd based file documenting the generator object (actual class).
2. Brief list of the RC methods in the Rd class documentation (in the Class-based methods section). This could perhaps be the first line of the docstring.
3. Comprehensive method based documentation should be provided in the method's docstring. That raises the question about the docstring's format. My suggestion is as follows (wrapped in ""):

Brief one line description of method
  Fuller description of method. Note this section's indent
 
Arguments
  `argument1`: note the indent
  `argument2`: note the indent

Return value or side effects
  Description of method's side-effects or return value. Note the Indent.

Examples
  Examples here. Note the indent

Note the use of markdown like syntax. For example, where \code{argument1} would have been used in an Rd file, argument1 is used instead.

Some notes on roxygen

1. It does not have a equivalent tag for the S4 class tag @slot. I am currently going to use @slot. A comment about this has been made on the roxygen repo in an issue related to RC documentation.
2. Hadley also suggests using docstrings to document RC methods. He also suggests using a roxygen block that is assigned to the NULL object and that specifies a "conventional" name for the Rd file. The latter seems to fly in the face of the official guidance and avoids the use of docstrings altogether (or perhaps mostly).

Resources

1. ?ReferenceClasses

Not sure what you mean in 2. That's not something I'd suggest - just document the RC generator.

See Advanced R programming - Documenting R5 methods:

Currently there is no way to use roxygen to document R5 methods. Use the standard docstring format. Alternatively, use roxygen to document an object with @name named by convention and assign it to NULL