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

[Andrew Redd]

On Tue, Dec 20, 2011 at 7:20 AM, Hadley Wickham <hadley at rice.edu> wrote:
>> 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?
The problem here is that people have to know that the object they have
is a reference class.  At the moment most users I would wager are
unaware of the existence of reference classes let alone knowing how to
obtain documentation from them.  It is a great idea but is new,
different and not obvious.  There should be way to link to Rd
Documentation and the internal 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 documentation here is very good but does not allow for easy
scanning of tags.  Also not all tags are represented (eg.
exportPattern)

>
>> 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?

I did provide an example but here is a very simple inline documentation example.
```r
#' @title Addition
add <- function(
   x #' @param x a number
  ,y #' @param y another number
){
  #' @section details
  #' performs addition of two objects.
  return x+y #' @return a number that is the sum of x and y
}
```
This way x and y are documented in place where they are defined, and
the return value is documented where it is defined.  As far as
literate programming goes this is the principle that code is
documented where it is written, as close to where it is written as
possible.

>
>> 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

I think it would be worthwhile and would be willing to contribute what
I could towards it.

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

See my above comment that R5 documentation should be to the extent
possible conform to previous expectations.

>
>> 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/