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

[Steve Lianoglou]

Ah, great!

Thanks for the refs, I'll look into them.

-steve

On Thu, Oct 1, 2009 at 1:12 PM, baptiste auguie
<baptiste.auguie at googlemail.com> wrote:
> 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.
>>
>



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