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

[Michael Lawrence]

On Fri, Dec 16, 2011 at 3:10 PM, Andrew Redd <amredd at gmail.com> wrote:

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


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