GenDBWiki/DeveloperDocumentation/DocumentationGuidelines

GenDB Source Code Documentation Guidelines

Below you can find some guidelines for writing you own source code within the GenDB system and for documenting the methods that you have written.

Writing inline POD documentation

For the documentation of all classes and their methods we are using inline POD documentation that can be translated into various other formats. Usually a complete module or class documentation contains the following sections:

• NAME -- the name of the current module or class
• SYNOPSIS -- a piece of source code showing a default example (not always necessary)
• DESCRIPTION -- detailed description of the current module or class
  • Available methods -- all API methods (see below); if you have a lot of methods you should group them into specific subsections
• SEE ALSO -- references to other modules or links to further information

Thus a typical module header might look like this:

=head1 NAME

GENDB::DB_Server::Region::CDS

=head1 DESCRIPTION

Server side extensions to class L<GENDB::DB::Region::CDS>.

=head2 Additional methods

=over 4

=cut

use strict;
use warnings;

... more includes ...

... maybe some constant definitions ...


our ($VERSION) = ('$Revision: 1.40 $ ' =~ /([d.]+)/g);
1;

Especially all methods useful for other programmers should be documented carefully.

Please DO NOT write the documentation of ALL methods at the beginning of a module. Instead, you should add the POD documentation right in front of each single method as shown below:

=item * STRING B<stop_codon>()

Get the stop codon of a CDS region.

  RETURNS: string containing the stop codon of a CDS region

=cut

sub stop_codon {
    my ($self) = @_;

    return substr($self->sequence, -3, 3);
}



=item * STRING B<aasequence>()

Get the amino acid sequence of the translated CDS. The AA sequence does not include the stop codon.

  RETURN: the corresponding amino acid sequence of a CDS region as a string

=cut

sub aasequence {
    my ($self) = @_;

    my $aaseq = ...;

    return $aaseq;
} 

If a method has a number of arguments (parameters) each of them should be documented in detail as well:

=item * STRING B<sequence>(from, to)

Get the DNA sequence of a region. A subsequence may be specified by from and to values (based on indexing starting with 1).

  from: optional integer value specifying a start position for sequence retrieval
  to: optional integer value specifying a stop position for sequence retrieval
  RETURNS: corresponding DNA sequence as string

=cut

sub sequence {
    my ($self, $from, $to) = @_;

    my $sequence = ...;

    return $sequence;
}

For optimized visualization of the POD output you should always add a newline before all arguments are described and you should also describe the RETURN value(s) if any.

Please DO NOT write POD documentation for internal methods that are only used (e.g. as helper functions) within a module. These methods should be implemented at the bottom of a module and all internal method names should start with '_'. You should of course document them by normal Perl comments (starting with '#').

###
# Internal methods that are not part of the 'visible' API
###


#
# Hooks into the pre-delete chain and removes all sub regions, observations
# and annotations associated to this region from the database
#
sub pre_delete_hook {
    my ($self) = @_;
    
    # delete all sub regions first
    ...

    return;
}

At the end of most modules you will often find references to other modules as show below:

=back

=head1 SEE ALSO

L<GENDB::DB::Region>

L<GENDB::DB_Server::Region.pm>

Some suggestions for pretty sources

Here are some DOs and DON'Ts for writing source code within the GenDB system:

DO	DON'T
($abc)	( $abc )
if ($test) {	if( $test ){
unless ($test)	unless($test)
while (...) {	while(...){
my (...)	my(...)
) {	){
$a->$b	$a -> $b