[Bioc-devel] refactoring

[Vincent Carey 525-2265]

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