[R] Looking for a better way to document my packages
Steve Lianoglou
mailinglist.honeypot at gmail.com
Thu Oct 1 18:58:53 CEST 2009
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
More information about the R-help
mailing list