[Bioc-devel] refactoring
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}}