GenDBWiki/DeveloperDocumentation/DocumentationGuidelines - Revision history

Admin: 7 revisions

2011-10-26T06:16:14Z

7 revisions

← Older revision	Revision as of 08:16, 26 October 2011
(No difference)

imported>AlexanderGoesmann at 09:30, 13 January 2005

2005-01-13T09:30:18Z

← Older revision		Revision as of 11:30, 13 January 2005
Line 50:		Line 50:
	</nowiki></pre>		</nowiki></pre>


			Each module should define the '''$VERSION''' variable as shown above.

	Especially all methods useful for other programmers should be documented carefully.		Especially all methods useful for other programmers should be documented carefully.
Line 92:		Line 94:
	</nowiki></pre>		</nowiki></pre>


			Leave '''three blank newlines''' in between two methods in order to increase the readability.

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


	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.		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 '#').		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 '_'. Only the predefined hooks provided by O2DBI do not start with '_'. You should of course document them by normal Perl comments (starting with '#').


Line 129:		Line 133:
	# Internal methods that are not part of the 'visible' API		# Internal methods that are not part of the 'visible' API
	###		###


			#
			# count the numbers of the CDS features
			#
			sub _count_cds_features {
			my ($self) = @_;

			my %counter = ...;

			return \%counter;
			}



Line 168:		Line 185:

	{\| border="1" cellpadding="2" cellspacing="0"		{\| border="1" cellpadding="2" cellspacing="0"
	\| DO		\| '''DO'''
	\| DON'T		\| '''DON'T'''
	\|-		\|-
	\| ($abc)		\| ($abc)

imported>AlexanderGoesmann at 17:58, 11 January 2005

2005-01-11T17:58:48Z

← Older revision	Revision as of 19:58, 11 January 2005
(No difference)

imported>AlexanderGoesmann at 17:55, 11 January 2005

2005-01-11T17:55:27Z

← Older revision		Revision as of 19:55, 11 January 2005
Line 1:		Line 1:
	__NOTOC__		__NOTOC__
	= GenDB Source Code ~~Documentation~~ Guidelines =		= GenDB Source Code 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.		Below you can find some guidelines and suggestions for writing you own source code within the GenDB system and for ''documenting'' the methods that you have written.

			== Writing new GenDB source code ==

			If you are implementing new cool stuff within the GenDB CORE, WEB, or GUI component you should always ask yourself if you are writing a specific method in the right place. As an example, if you are implementing some functionality that could not only be used within the GUI but also in the web interface you should store that stuff only once in a backend module of the CORE component. Before you commit any changes you should of course update your CVS tree to the latest stage, test the new functionality and check everything carefully. Larger modifications should always be announced to the GenDB developer mailing list. If you have made changes in several modules please ensure that you commit all parts that are affected. If you encouter conflicts - try to resolve them. For more complex tasks it is also a good idea to have a little script that tests and checks this funtionality; we are currently looking for a way to incorporate a unit test system into GenDB.

	== Writing inline POD documentation ==		== Writing inline POD documentation ==

imported>AlexanderGoesmann at 17:14, 11 January 2005

2005-01-11T17:14:23Z

← Older revision		Revision as of 19:14, 11 January 2005
Line 174:		Line 174:
	\|-		\|-
	\| unless ($test)		\| unless ($test)
	\| unless ($test)		\| unless($test)
	\|-		\|-
	\| while		\| while (...) {
	\| => while (		\| while(...){
			\|-
			\| my (...)
			\| my(...)
			\|-
			\| ) {
			\| ){
			\|-
			\| $a->$b
			\| $a -> $b
	\|}		\|}
	~~my( => my (~~
	~~){ => ) {~~
	~~_-> => ->~~
	~~->_ => ->~~

imported>AlexanderGoesmann at 13:21, 11 January 2005

2005-01-11T13:21:33Z

← Older revision		Revision as of 15:21, 11 January 2005
Line 141:		Line 141:

	</nowiki></pre>		</nowiki></pre>


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


			<pre><nowiki>

			=back

			=head1 SEE ALSO

			L<GENDB::DB::Region>

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

			</nowiki></pre>


			== Some suggestions for pretty sources ==

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

			{\| border="1" cellpadding="2" cellspacing="0"
			\| DO
			\| DON'T
			\|-
			\| ($abc)
			\| ( $abc )
			\|-
			\| if ($test) {
			\| if( $test ){
			\|-
			\| unless ($test)
			\| unless ($test)
			\|-
			\| while
			\| => while (
			\|}
			my( => my (
			){ => ) {
			_-> => ->
			->_ => ->

imported>AlexanderGoesmann at 12:35, 11 January 2005

2005-01-11T12:35:10Z

Unknown user at 00:00, 1 January 1970

1970-01-01T00:00:00Z

New page

__NOTOC__
= 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:

<pre><nowiki>

=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;

</nowiki></pre>

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:

<pre><nowiki>

=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;
}

</nowiki></pre>

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

<pre><nowiki>

=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;
}

</nowiki></pre>

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 '#').

<pre><nowiki>

###
# 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;
}

</nowiki></pre>

← Older revision		Revision as of 14:35, 11 January 2005
Line 2:		Line 2:
	= GenDB Source Code Documentation Guidelines =		= 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.		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 ==		== Writing inline POD documentation ==
Line 8:		Line 8:
	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:		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		* NAME -- the name of the current module or class
	* !SYNOPSIS -- a piece of source code showing a default example (not always necessary)		* SYNOPSIS -- a piece of source code showing a default example (not always necessary)
	* !DESCRIPTION -- detailed description of the current module or class		* 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		** 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		* SEE ALSO -- references to other modules or links to further information

	Thus a typical module header might look like this:		Thus a typical module header might look like this:
Line 115:		Line 115:


	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.		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 '#').		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 '#').