[BioRuby] rdoc specs

[jan aerts (RI)]

> It also seems like we have two styles of "class" and I'm not sure  
> what words to use to distinguish them.  There are the primary public- 
> API classes that should have extensive documentation with examples  
> and use cases (as well as formal arguments and return values), but  
> then there are all the little classes that help out the main  
> interfaces that don't need nearly as much documentation (but should  
> still have documented the formal arguments, etc.).  What should we be  
> calling those?  How do we make the formal distinction?

I believe BioPerl takes the approach of having _interface_ and _implementation_ objects to solve a similar issue. See http://www.bioperl.org/wiki/Advanced_BioPerl#Bioperl_Interface_design and http://www.bioperl.org/wiki/Advanced_BioPerl#Rationale_of_Interface_Design

I'm far from familiar with language design issues, but it might be an idea to have a look at it. I also might be talking about something completely different without knowing it, in which case: my apologies.

jan.

Dr Jan Aerts
Bioinformatics Group
Roslin Institute
Roslin EH25 9PS
Scotland, UK
tel: +44 131 527 4200
skype: aerts_ri