[BioRuby] rdoc specs

[Trevor Wennblom]

I took a shot at putting together some formal specs for our rdoc  
comments as it pertains to file and class level documentation.   
Please comment if you have anything to add or disagree with any  
aspect.  I'll likely add this to the README file later this week if  
everything looks okay.

I also didn't bother to mention the "$Id" lines since svn doesn't use  
those and we'll likely phase them out.

Thanks,
Trevor

---

Example structure of file-level and class-level RDoc comments for a  
BioRuby
source file:
   # bio/subdirectory/yourfilefilename.rb - One-line brief  
description of file contents
   #
   # Author::    Your Name (and optionally your email address)
   # Copyright:: Copyright (c) 2006-2009 Whoever Has The Copyright
   # License::   The Ruby License

   nil  # This line is required if you do not have any other code  
before 'module Bio'

   module Bio

   # Author::    Your Name (and optionally your email address)
   # Copyright:: Copyright (c) 2006-2009 Whoever Has The Copyright
   # License::   The Ruby License
   #
   # = Description
   # A brief description of your class.
   #
   # = Usage
   # Examples of how to use your class.

   class YourClass
   end

   end

Here is another example of an acceptable attribution style:
   # bio/subdirectory/filename.rb - One-line brief description of  
file contents
   #
   # Copyright::   Copyright (c) 2004-2007
   #               Your Name <yourname at example.com>,
   #               Another Author <mailto:person at example.com>
   # License::     The Ruby License

* Attribution can be added by the author, or copyright may be given  
to the
BioRuby project itself and the team will then add the appropriate  
attribution.
* Class-level attribution is optional.  You may find it appropriate  
in some
cases and not in others.  This is what will appear in the generated  
RDoc when
people are reading about how to use a class as opposed to inspecting  
the file
contents.
* A singular line of 'nil' must separate the file-level documentation  
from the
"module Bio" line if there is no other code to separate the module  
declaration
from the comments.  If this is not done comments for the Bio module  
will be
overwritten.
* 'Description' and 'Usage' for class-level documentation should be  
included
if it is meant to be publicly used.  If there is no reason to include  
verbose
documentation consider adding the "class YourClass # :nodoc:"  
declaration to
keep the generated RDoc tidy.
* You could also include a tutorial, references, or whatever you  
think is
pertinent.
* If you would like to separate a large piece of documentation from  
your code
you may include a separate file with the "# :include:  
yourfilename.rb.rdoc"
RDoc statement
* The copyright line should include lowercase "(c)" for RDoc conversion.
* The first line of the file-level documentation should resemble
"# bio/subdirectory/yourfilefilename.rb - comments".  This should be  
on a
single line with a brief description of the contents.  This line may  
be any
length.