Message-ID: <Pine.GSO.4.58.0804141458320.19468@capecod.bwh.harvard.edu>
Date: 2008-04-14T19:03:18Z
From: Vincent Carey
Subject: [Bioc-devel] refactoring
In-Reply-To: <06AD25DA-8799-458F-9DA6-1A2AFDA41668@berkeley.edu>
On Fri, 11 Apr 2008, James Bullard wrote:
> Hi All, I have a quick question about refactoring (mostly
> documentation). I have a set of classes which all have a method
> defined on them:
>
> setClass("c1", representation(x = "numeric"))
> setClass("c2", representation(x = "numeric"))
> setClass("c3", representation(x = "numeric"))
>
> setGeneric("m", def = function(klass) standardGeneric("m"))
> setMethod("m", signature("c1"), function(klass) { klass at x^2 })
> setMethod("m", signature("c2"), function(klass) { klass at x^3 })
> setMethod("m", signature("c3"), function(klass) { klass at x^4 })
>
> When I do promptClass on these classes I am happy and I get some
> boilerplate .Rd to fill in. However, if, once I have my nice .Rd files
> for the set of classes and I come along and make a new method I want
> to be able to add to the .Rd files the boilerplate for this new method
> so R CMD CHECK doesn't complain. Also, if I decide to export a method
> that was not exported previously then I have the same problem. I was
> wondering if people do particular things - it is not clear to me that
> any simple diff will work, but I was hoping that someone might have
> something because it is quite tedious to edit these files by hand,
> especially when you have a reasonable class hierarchy.
>
> Why this question is posted to the bioc-devel list is that I was
> wondering also does bioc have any kind of document generation
> aspirations? I know that this has come up a number of times, but
> maintaining documentation is becoming too much of a burden and that
> generally means that I do a poor job. I didn't notice any discussion
> on: http://wiki.fhcrc.org/bioc/DeveloperPage#discussions, so maybe
> people are using other documentation utilities. I know that Henrik has
> his utilities, but I was hoping maybe there was a bioc standard and I
> could use that.
>
I suspect this problem is felt in many development sectors. Incremental
promptClass should be possible if you have a reasonable .Rd parser/serializer.
There must be sufficient facilities for this in R, but putting them together
for a reliable incremental doc processor is probably nontrivial.
I believe someone is just going to have to bite the bullet and start
such a project. There are projects related to documentation in the
Google Summer of Code proposals, I think, and so you might drop this
query into R-devel.
The information transmitted in this electronic communica...{{dropped:10}}