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

[Andrew Redd]

roxygen users,
I'm new to the list, so please forgive my naivete.  I'm also getting
used to using roxygen2 package for documentation.  I have used doxygen
a little in the past.

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.

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?

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.

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.

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.

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?


Thank you for suffering with a very long email and lots of questions.

Andrew Redd