<br><br><div class="gmail_quote">On Fri, Dec 16, 2011 at 3:10 PM, Andrew Redd <span dir="ltr"><<a href="mailto:amredd@gmail.com">amredd@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
roxygen users,<br>
I'm new to the list, so please forgive my naivete. I'm also getting<br>
used to using roxygen2 package for documentation. I have used doxygen<br>
a little in the past.<br>
<br>
I saw the discussion on the archive about S4 documentation. My<br>
opinion is that methods should at the very least be included in the<br>
class documentation, but as far as including the documentation in the<br>
generic, I'm not quite sure I see how that is to be accomplished.<br>
Many of the generics that people will be using, predict being an<br>
example, exists in the stats package, which is part of base R. Unless<br>
each package modifes the documentation for predict appending the<br>
methods that it adds I don't see how generic-centric documentation<br>
would be possible.<br>
<br></blockquote><div><br><br>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.<br>
<br></div><blockquote class="gmail_quote" style="margin:0pt 0pt 0pt 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
Some of my packages use S4 but for the most part I've moved onto R5<br>
reference classes that interface Rcpp and java classes. Does anyone<br>
have any good examples of documenting an R5 class?<br>
<br>
This brings me to a first question. Is there a comprehensive wiki or<br>
documentation where one could see all the tags available and examples<br>
of documentation, such as package, class, s3 methods, s4 class and<br>
methods, R5 documentation? even a collection of links would be great<br>
to learn from. Hadley has the documentation for ggplot2 on his site<br>
and on the github wiki at<br>
<a href="https://github.com/hadley/ggplot2/wiki/%2Bopts%28%29-List" target="_blank">https://github.com/hadley/ggplot2/wiki/%2Bopts%28%29-List</a> which I<br>
reference often.<br>
<br>
The second issues that comes from my doxygen experience is if there is<br>
a way that we can extract inline documentation. From the beginning<br>
roxygen only looked at documentation before a function. But doxygen<br>
looks at the entire function for comments. The Google R Coding<br>
standards specifies that the comments be inside the function block.<br>
This provides for useful code folding that swallows up the<br>
documentation as well for nice and tidy code.<br>
<br>
The other possibility is that for methods the code can be put inline<br>
consider the documenation I have for one of my projects.<br>
```r<br>
#' Transmission Model Class<br>
#'<br>
#' Fits a transmission model for single ward or hospital.<br>
#' Wards are assumed to be open in that there are admissions and discharges.<br>
#' @import rJava<br>
#' @export<br>
TransmissionModel <- setRefClass("TransmissionModel",<br>
fields = list( sampler="jobjRef"),<br>
methods= list(<br>
initialize = function(patient.data, test.data,<br>
patient.vars = plyr::.(pid=pid, admit=admit, discharge=discharge),<br>
test.vars = plyr::.(pid=pid, time=time, result=result),<br>
<a href="http://show.net" target="_blank">show.net</a>=interactive(), progress=interactive(), progress.type='text',<br>
deltatime=1){<br>
#' Initializes the java mcmc sampler with the patient and swab data.<br>
#' @param patient.data Patients data frame<br>
#' @param test.data tests data frame , must have a variable<br>
identifying patients in patient.data.<br>
#' @param patient.vars mapping for the variables in the<br>
patient.data. Use .() notation. See Details<br>
#' @param test.vars mapping for tests variables. Use .()<br>
notation. See Details.<br>
#' @param deltatime delta time, the discrete time unit.<br>
...<br>
```<br>
Here I set a reference class with documentation for a method<br>
initialize and what parameters to call it with. Of course right now<br>
only the block before the code is considered. If possible I highly<br>
recommend altering roxygen to accept this kind of documentation.<br>
Inline blocks for methods should perhaps include a `@r5method name`<br>
but be extracted as a continuous block for building the rd file. The<br>
documentation is already distinguished from regular comments by the #'<br>
comment.<br>
<br>
Similar to the java example I gave above Rcpp exported classes need to<br>
be documented as well. I read of having \Sexpr to extract<br>
documentation in the emails from last month. Is there an example of<br>
using this somewhere? again back to the idea of having a wiki. Does<br>
that work with building packages? and does that mean that packages<br>
are built after installation?<br>
<br>
<br>
Thank you for suffering with a very long email and lots of questions.<br>
<span class="HOEnZb"><font color="#888888"><br>
Andrew Redd<br>
_______________________________________________<br>
Roxygen-devel mailing list<br>
<a href="mailto:Roxygen-devel@lists.r-forge.r-project.org">Roxygen-devel@lists.r-forge.r-project.org</a><br>
<a href="https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/roxygen-devel" target="_blank">https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/roxygen-devel</a><br>
</font></span></blockquote></div><br>