[R] Looking for a better way to document my packages

[Steve Lianoglou]

Hi all,

Trying to do what my subject says.

As I'm trying to be better about making packages out of my code, I'd  
like the packages themselves to be better, which means *.Rd- 
documenting my code. The thing is, from years of programming other  
languages prior to landing in the R pond, I've grown accustomed to  
documenting my functions inline. I'm not just used to it, but I like  
it more than having function documentation completely removed from my  
function, code.

So, for example

myNeatFunction <- function(arg1, arg2, arg3=NULL, ...) {
   # One liner describing the neat thing this function does.
   #
   # More comments, probably very much what would be in the
   # \description section of the *Rd
   #
   # Parameters
   # ----------
   # arg1 : <some comments>
   # arg2 : <some comments>
   # ... This is essentially the same exact stuff that would
   # be in the \arguments{} section of the *.Rd
   #
   # Returns
   # -------
   # A description of what's returned, let's say this is
   # what you'd find in the \value{} section.
   #
   # Notes
   # -----
   # Maybe something like the \details{} section, though this
   # might as well be up in the description section, too.
   # etc.
}

There's essentially a 1-to-1 mapping of the comments I write here and  
what I would write in an *.Rd file, but I'd rather have it written in  
my function definition than an external document.

Are there any tools that help facilitate this? Or are there better  
ways you folks have figured out to do something similar?

I don't need the function comment block to be exactly what I showed  
here, but it's just an example of how I'm currently writing my stuff.  
I'm thinking something like sphinx (http://sphinx.pocoo.org/) from the  
python world would be cool. Perhaps there's a way to make a plugin for  
that to parse R-code. That's more work than I want to bit off right  
now, but if there isn't something useful in R-land already, it might  
be a fun side project.

Just curious,
-steve

--
Steve Lianoglou
Graduate Student: Computational Systems Biology
   |  Memorial Sloan-Kettering Cancer Center
   |  Weill Medical College of Cornell University
Contact Info: http://cbio.mskcc.org/~lianos/contact