[Roxygen-devel] inline documentation, R5, and where can I find the examples?

[Hadley Wickham]

> I  saw the discussion on the archive about S4 documentation.  My
> opinion is that methods should at the very least be included in the
> class documentation, but as far as including the documentation in the
> generic, I'm not quite sure I see how that is to be accomplished.
> Many of the generics that people will be using, predict being an
> example, exists in the stats package, which is part of base R.  Unless
> each package modifes the documentation for predict appending the
> methods that it adds I don't see how generic-centric documentation
> would be possible.

It is currently impossible, but there is some hope that R core might
adopt a standard (partially informed by roxygen) that makes it
possible to automatically include method docs (or a least a list of
methods) automatically using \Sexpr tags.

> Some of my packages use S4 but for the most part I've moved onto R5
> reference classes that interface Rcpp and java classes.  Does anyone
> have any good examples of documenting an R5 class?

I don't.  Have you read ?referenceClasses for John Chambers suggested
form of documentation?

> This brings me to a first question.  Is there a comprehensive wiki or
> documentation where one could see all the tags available and examples
> of documentation, such as package, class, s3 methods, s4 class and
> methods, R5 documentation?  even a collection of links would be great
> to learn from. Hadley has the documentation for ggplot2 on his site
> and on the github wiki at
> https://github.com/hadley/ggplot2/wiki/%2Bopts%28%29-List which I
> reference often.

They should all be listed in the help for individual roclets:
?rd_roclet, ?namespace_roclet, ?collate_roclet etc.

> The second issues that comes from my doxygen experience is if there is
> a way that we can extract inline documentation.  From the beginning
> roxygen only looked at documentation before a function.  But doxygen
> looks at the entire function for comments.  The Google R Coding
> standards specifies that the comments be inside the function block.
> This provides for useful code folding that swallows up the
> documentation as well for nice and tidy code.

Could you provide an example?

> The other possibility is that for methods the code can be put inline
> consider the documenation I have for one of my projects.
> ```r
> #' Transmission Model Class
> #'
> #' Fits a transmission model for single ward or hospital.
> #' Wards are assumed to be open in that there are admissions and discharges.
> #' @import rJava
> #' @export
> TransmissionModel <- setRefClass("TransmissionModel",
>   fields = list( sampler="jobjRef"),
>   methods= list(
>     initialize = function(patient.data, test.data,
>       patient.vars = plyr::.(pid=pid, admit=admit, discharge=discharge),
>       test.vars = plyr::.(pid=pid, time=time, result=result),
>       show.net=interactive(), progress=interactive(), progress.type='text',
>       deltatime=1){
>       #' Initializes the java mcmc sampler with the patient and swab data.
>       #' @param patient.data Patients data frame
>       #' @param test.data tests data frame , must have a variable
> identifying patients in patient.data.
>       #' @param patient.vars mapping for the variables in the
> patient.data.  Use .() notation.  See Details
>       #' @param test.vars  mapping for tests variables.  Use .()
> notation.  See Details.
>    #' @param deltatime delta time, the discrete time unit.
> ...
> ```
> Here I set a reference class with documentation for a method
> initialize and what parameters to call it with.  Of course right now
> only the block before the code is considered.  If possible I highly
> recommend altering roxygen to accept this kind of documentation.
> Inline blocks for methods should perhaps include a `@r5method name`
> but be extracted as a continuous block for building the rd file.  The
> documentation is already distinguished from regular comments by the #'
> comment.

This is challenging for two reasons:

1) We'd have to make quite a few changes to the parser to capture
comments inside functions

2) There's currently no standard way of looking up documentation for
R5 methods.

> Similar to the java example I gave above Rcpp exported classes need to
> be documented as well. I read of having \Sexpr to extract
> documentation in the emails from last month.  Is there an example of
> using this somewhere?  again back to the idea of having a wiki.  Does
> that work with building packages?  and does that mean that packages
> are built after installation?

\Sexpr is something that roxygen would use, and users would hopefully
be insulated from it.  If you're interested, you can read about it the
R packages manual, but in my experience it's still a bit raw, and R
core and still working out the kinks.

Hadley


-- 
Assistant Professor / Dobelman Family Junior Chair
Department of Statistics / Rice University
http://had.co.nz/