RC generators should be documented the same way S4 objects are documented. However, there is no convention to documenting RC methods.
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:
- Name
- Document type
- Aliases
- Title
- Description
- Extends
- Methods
- References
- Author
- Note
- See also
- Examples
- Keyword
- Fields
- 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.
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.
RC documentation should consist of:
- Rd based file documenting the generator object (actual class).
- 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.
- 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.
- 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. - 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).
?ReferenceClasses
Not sure what you mean in 2. That's not something I'd suggest - just document the RC generator.