[BioRuby-cvs] bioruby README.DEV,1.9,1.10

Thu May 11 10:53:27 UTC 2006

Update of /home/repository/bioruby/bioruby
In directory dev.open-bio.org:/tmp/cvs-serv26709

Modified Files:
	README.DEV 
Log Message:
Added documentation on standard documentation of files and modules (as requested by Toshiaki).

Index: README.DEV
===================================================================
RCS file: /home/repository/bioruby/bioruby/README.DEV,v
retrieving revision 1.9
retrieving revision 1.10
diff -C2 -d -r1.9 -r1.10
*** README.DEV	8 Feb 2006 12:02:09 -0000	1.9
--- README.DEV	11 May 2006 10:53:25 -0000	1.10
***************
*** 1,9 ****
! =begin
! 
!   $Id$

!   Copyright (C) 2005, 2006 Toshiaki Katayama <k at bioruby.org>

! = How to contribute to the BioRuby project?

  There are many possible ways to contribute to the BioRuby project,
--- 1,8 ----
! $Id$

! Copyright (C):: 2005, 2006 Toshiaki Katayama <k at bioruby.org>
! Copyright (C):: 2006       Jan Aerts <jan.aerts at bbsrc.ac.uk>

! = HOW TO CONTRIBUTE TO THE BIORUBY PROJECT?

  There are many possible ways to contribute to the BioRuby project,
***************
*** 21,25 ****
  your module meets the field of bioinformatics.

! == License

  If you would like your module to be included in the BioRuby distribution,
--- 20,24 ----
  your module meets the field of bioinformatics.

! = LICENSE

  If you would like your module to be included in the BioRuby distribution,
***************
*** 30,38 ****
  are changing the license to Ruby's. 

! == Coding style

  You will need to follow the typical coding styles of the BioRuby modules:

! === Use the following naming conventions

  * CamelCase for module and class names
--- 29,37 ----
  are changing the license to Ruby's. 

! = CODING STYLE

  You will need to follow the typical coding styles of the BioRuby modules:

! == Use the following naming conventions

  * CamelCase for module and class names
***************
*** 41,101 ****
  * all UPPERCASE for constants

! === Indentation must not include tabs

  * Use 2 spaces for indentation.
  * Don't replace spaces to tabs.

! === Comments

! Don't use =begin and =end blocks for comments.  If you need to add
  comments, include it in the RDoc documentation.

! === Each file must start with the following text

    #
!   # = bio/db/hoge.rb - Hoge database parser
    #
-   # Copyright::   Copyright (C) 2001, 2005
-   #               Bio R. Hacker <brh at example.org>,
-   #               Chem R. Hacker <crh at example.org>
    # License::     Ruby's
    #
    # $Id$
    #
!   # == Blah blah blah
!   #
!   # See http://hoge.db/ for more details on the Hoge database.
!   # ... blah blah blah ...
!   #
!   # == Examples
    #
!   #   hoge = Bio::Hoge.new(entry)
!   #   puts hoge.entry_id
!   #   puts hoge.definition
    #
!   # == References
    #
    # * Hoge F. et al., The Hoge database, Nucleic. Acid. Res. 123:100--123 (2030)
-   #
    # * http://hoge.db/
    #

! === Documentation should be written in the RDoc format in the source code

! The RDoc format is becoming the popular standard for Ruby documentation.
! We are now in transition from the previously used RD format to the RDoc
! format in API documentation.

! Additional tutorial documentation and working examples are encouraged
! with your contribution.  You may use the header part of the file for
! this purpose as demonstrated in the previous section.

! === Testing code should use 'test/unit'

  Unit tests should come with your modules by which you can assure what
  you meant to do with each method.  The test code is useful to make
! maintenance easy and ensure stability.

! === Using autoload

  To quicken the initial load time we have replaced most of 'require' to 
--- 40,205 ----
  * all UPPERCASE for constants

! == Indentation must not include tabs

  * Use 2 spaces for indentation.
  * Don't replace spaces to tabs.

! == Comments

! Don't use <tt>=begin</tt> and <tt>=end</tt> blocks for comments.  If you need to add
  comments, include it in the RDoc documentation.

! == Documentation should be written in the RDoc format in the source code
! 
! The RDoc format is becoming the popular standard for Ruby documentation.
! We are now in transition from the previously used RD format to the RDoc
! format in API documentation.
! 
! Additional tutorial documentation and working examples are encouraged
! with your contribution.  You may use the header part of the file for
! this purpose as demonstrated in the previous section.
! 
! == Standard documentation
! 
! === of files
! 
! Each file should start with a header, which covers the following topics:
! * copyright
! * license
! * description of the file (_not_ the classes; see below)
! * any references, if appropriate

+ The header should be formatted as follows:
    #
!   # = bio/db/hoge.rb - Hoge database parser classes
!   #
!   # Copyright (C):: 2001, 2003-2005   Bio R. Hacker <brh at example.org>,
!   # Copyright (C):: 2006              Chem R. Hacker <crh at example.org>
    #
    # License::     Ruby's
    #
    # $Id$
    #
!   # = Description
    #
!   # This file contains classes that implement an interface to the Hoge database.
    #
!   # = References
    #
    # * Hoge F. et al., The Hoge database, Nucleic. Acid. Res. 123:100--123 (2030)
    # * http://hoge.db/
    #

! In the above sample, the
!   $Id$
! will be automatically changed into something like
!   $Id$
! when commiting to the CVS repository for the first time.

! === of classes and methods within those files

! Classes and methods should be documented in a standardized format, as in the
! following example (from lib/bio/sequence.rb):

!   # = DESCRIPTION
!   # Bio::Sequence objects represent annotated sequences in bioruby.
!   # A Bio::Sequence object is a wrapper around the actual sequence, 
!   # represented as either a Bio::Sequence::NA or a Bio::Sequence::AA object.
!   # For most users, this encapsulation will be completely transparent.
!   # Bio::Sequence responds to all methods defined for Bio::Sequence::NA/AA
!   # objects using the same arguments and returning the same values (even though 
!   # these methods are not documented specifically for Bio::Sequence).
!   #
!   # = USAGE
!   #   require 'bio'
!   #   
!   #   # Create a nucleic or amino acid sequence
!   #   dna = Bio::Sequence.auto('atgcatgcATGCATGCAAAA')
!   #   rna = Bio::Sequence.auto('augcaugcaugcaugcaaaa')
!   #   aa = Bio::Sequence.auto('ACDEFGHIKLMNPQRSTVWYU')
!   # 
!   #   # Print in FASTA format
!   #   puts dna.output(:fasta)
!   # 
!   #   # Print all codons
!   #   dna.window_search(3,3) do |codon|
!   #     puts codon
!   #   end
!   # 
!   class Sequence
!   
!     # Create a new Bio::Sequence object
!     #
!     #   s = Bio::Sequence.new('atgc')
!     #   puts s                                  #=> 'atgc'
!     #
!     # Note that this method does not intialize the contained sequence
!     # as any kind of bioruby object, only as a simple string
!     #
!     #   puts s.seq.class                        #=> String
!     #
!     # See Bio::Sequence#na, Bio::Sequence#aa, and Bio::Sequence#auto 
!     # for methods to transform the basic String of a just created 
!     # Bio::Sequence object to a proper bioruby object
!     # ---
!     # *Arguments*:
!     # * (required) _str_: String or Bio::Sequence::NA/AA object
!     # *Returns*:: Bio::Sequence object
!     def initialize(str)
!       @seq = str
!     end
!   
!     # The sequence identifier.  For example, for a sequence
!     # of Genbank origin, this is the accession number.
!     attr_accessor :entry_id
!   
!     # An Array of Bio::Feature objects
!     attr_accessor :features
!   end # Sequence
! 
! Preceding the class definition (<tt>class Sequence</tt>), there is at least a 
! description and a usage example. Please use the +Description+ and +Usage+
! headings. If appropriate, refer to other classes that interact with or are
! related to the class.
! 
! The code in the usage example should, if possible, be in a format that a user
! can copy-and-paste into a new script to run. It should illustrate the most
! important uses of the class. If possible and if it would not clutter up the
! example too much, try to provide any input data directly into the usage example,
! instead of refering to ARGV or ARGF for input.
!   dna = Bio::Sequence.auto('atgcatgcATGCATGCAAAA')
! Otherwise, describe the input shortly, for example:
!   # input should be string consisting of nucleotides
!   dna = Bio::Sequence.auto(ARGF.read)
! 
! Methods should be preceded by a comment that describes what the method does, 
! including any relevant usage examples. (In contrast to the documentation for
! the class itself, headings are not required.) In addition, any arguments should
! be listed, as well as the type of thing that is returned by the method. The
! format of this information is as follows:
!   # ---
!   # *Arguments*:
!   # * (required) _str_: String or Bio::Sequence::NA
!   # * (optional) _nr_: a number that means something
!   # *Returns*:: true or false
! 
! Attribute accessors can be preceded by a short description.
! 
! == Exception handling
! 
! Don't use
!   $stderr.puts "WARNING"
! in your code. Instead, try to avoid printing error messages. For fatal errors,
! use +raise+ with an appropriate message.
! 
! == Testing code should use 'test/unit'

  Unit tests should come with your modules by which you can assure what
  you meant to do with each method.  The test code is useful to make
! maintenance easy and ensure stability. The use of
!  if __FILE__ == $0
! is deprecated.

! == Using autoload

  To quicken the initial load time we have replaced most of 'require' to 
***************
*** 135,139 ****
    so autoload can be written in 1 line.

! == Name space

  Your module should be located under the top-level module Bio and put under
--- 239,243 ----
    so autoload can be written in 1 line.

! = NAMESPACE

  Your module should be located under the top-level module Bio and put under
***************
*** 151,161 ****

  If your module doesn't match any of the above, please propose
! an appropriate directory name when you contribute.

! == Maintenance

  Finally, please maintain the code you've contributed.  The BioRuby
  staff is willing to give you CVS privileges if needed.
! 
! =end

--- 255,267 ----

  If your module doesn't match any of the above, please propose
! an appropriate directory name when you contribute. Please let the staff
! discuss on namespaces (class names), API (method names) before commiting
! a new module or making changes on existing modules.

! = MAINTENANCE

  Finally, please maintain the code you've contributed.  The BioRuby
  staff is willing to give you CVS privileges if needed.
! Please let us know (on the bioruby list) before you commit, so that users
! can discuss on the change.