R help - Oct 2009 - Looking for a better way to document my packages

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

Hi,

I know of three options that resemble your query,

- the roxygen package

- a ruby script called weeder by Hadley Wikham

- the inlinedocs package on r-forge

I only ever used roxygen though, so i can't speak for the relative
merits of the others.

HTH,

baptiste


2009/10/1 Steve Lianoglou <mailinglist.honeypot at
gmail.com>:
> 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
>
> ______________________________________________
> R-help at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-help
> PLEASE do read the posting guide
http://www.R-project.org/posting-guide.html
> and provide commented, minimal, self-contained, reproducible code.
>