[BioRuby] rdoc specs
Trevor Wennblom
trevor at corevx.com
Mon Apr 23 21:10:39 UTC 2007
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.
More information about the BioRuby
mailing list