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

Post by 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.

I guess I don't see why one needs to modify the documentation of the
(implicit) generic in order to have generic-centric documentation. Roxygen
will in general not know whether a package providing a generic has been
roxygenized. Therefore, each package will need some dynamic document for
each generic it registers a method on.

Post by Andrew Redd
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.
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.
identifying patients in patient.data.
patient.data. Use .() notation. See Details
notation. See Details.
...
```
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.
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
_______________________________________________
Roxygen-devel mailing list
Roxygen-devel at lists.r-forge.r-project.org
https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/roxygen-devel

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.r-forge.r-project.org/pipermail/roxygen-devel/attachments/20111216/94579861/attachment.htm>

Hadley Wickham

2011-12-20 14:20:42 UTC

Post by Andrew Redd
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.

Post by Andrew Redd
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?

Post by Andrew Redd
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.

Post by Andrew Redd
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?

Post by Andrew Redd
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.
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.
identifying patients in patient.data.
patient.data. ?Use .() notation. ?See Details
notation. ?See Details.
...
```
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.
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.

Post by Andrew Redd
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/

Andrew Redd

2011-12-20 20:03:54 UTC

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.

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

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.

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.

Post by Hadley Wickham
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.

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

Hadley Wickham

2012-01-02 14:53:07 UTC

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.

Yes, but this needs to be an R standard, not a roxygen2 standard.
Otherwise it doesn't really help because people still won't know how
to find help!

One possible convention would to be use refclass?method to get help
about a method. This is somewhat confounded with the existing
standard for getting help about packages (package?mypackage) and S4
classes (class?myclass), but does have a nice parallel with the way
that R5 methods are called.

Post by Hadley Wickham
?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)

If you see any that are missing, please file a bug at
https://github.com/klutometis/roxygen/issues

Note that the Google style guide is effective the Tim Hesterburg style
guide and should not be treated as canonical.

Post by Andrew Redd
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
add <- function(
){
?#' performs addition of two objects.
}
```
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.

Personally, I really dislike this style of documentation. I much
prefer to have all the documentation in one place. That means that
this isn't something I would spend time working on, but I would accept
a well tested patch that implemented this style.

Hadley

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

Hadley Wickham

2012-01-02 14:55:12 UTC