[Roxygen-devel] Discussion of documentation examples.

[Manuel J. A. Eugster]

I provided some examples of documentation using Roxygen
(directory `pkg/sandbox/`).


Some explanations, obscurities and questions:

example-function-mcpi.R: documentation of a 'normal' function.
example-S3-mcpi.R: documentation of S3 class, generics and methods.
example-S4-person.R: documentation of S4 classes, generics and methods.


example-function-mcpi:

1) intra-object comments, as for variable `hits` and `xy` in ,
are ignored.

2) automatically detect default values of function parameters
(verbose=TRUE)?

3) @return with type of the return value?


example-S3-mcpi:

4) @return says that the function returns an object of class `mcpi`,
but there is no formal definition of this class; introduce a special
Roxygen documentation block for S3 classes?

5) @import is used by the NAMESPACE-Roclet. Maybe it is not possible to
detect automatically what the imported thing is (S3 class, S3 method,
S4 Class, ...), then we have to introduce more specific @import keywords.


example-S4-person:

6) @export is used by the NAMESPACE-Roclet; using regex it should be possible
to find out what the exported thing really is (S3/S4 class, ...) and what we
have to write into the NAMESPACE file.

7) Automatically detect type of the return value if `valueClass` is provided
in the definition of the generic?


Manuel.