pod documentation added

modules/Bio/EnsEMBL/Hive/ProcessWithParams.pm

-=pod
 
-This module extends Bio::EnsEMBL::Hive::Process by implementing param() method.
+=pod 
 
-A majority of Compara RunnableDB methods work under assumption
-that both analysis.parameters and analysis_job.input_id fields contain a Perl-style parameter hashref as a string.
+=head1 NAME
+
+Bio::EnsEMBL::Hive::ProcessWithParams
+
+=head1 SYNOPSIS
 
-This module implements the following capabilities:
-    1) parsing of these parameters in the right order of precedence (including built-in defaults, if supplied)
+This module extends Bio::EnsEMBL::Hive::Process by implementing the following capabilities:
+
+    1) parsing of parameters in the right order of precedence (including built-in defaults, if supplied)
             #
             # $self->param_init('taxon_id' => 10090, 'source' => 'UniProt');
             #
@@ -24,21 +27,63 @@ This module implements the following capabilities:
         Note: It proved to be a convenient mechanism to exchange params
               between fetch_input(), run(), write_output() and other methods.
 
+=head1 DESCRIPTION
+
+Most of Compara RunnableDB methods work under assumption
+that both analysis.parameters and analysis_job.input_id fields contain a Perl-style parameter hashref as a string.
+
+This module extends Bio::EnsEMBL::Hive::Process by implementing a generic param() method that sets module parameters
+accorting to the following parameter precedence rules:
+
+    (1) Job-Specific parameters defined in analysis_job.input_id hash, they have the highest priority and override everything else.
+
+    (2) Analysis-Wide parameters defined in analysis.parameters hash. Can be overridden by (1).
+
+    (3) Pipeline-Wide parameters defined in the 'meta' table. Can be overridden by (1) and (2).
+
+    (4) Module_Defaults that are hard-coded into modules have the lowest precedence. Can be overridden by (1), (2) and (3).
+
+=head1 CONTACT
+
+  Please contact ehive-users@ebi.ac.uk mailing list with questions/suggestions.
+
 =cut
 
+
 package Bio::EnsEMBL::Hive::ProcessWithParams;
 
 use strict;
 use Bio::EnsEMBL::Hive::Utils 'destringify';  # import 'destringify()'
 use base ('Bio::EnsEMBL::Hive::Process');
 
+
+=head2 strict_hash_format
+
+    Description: This public virtual method should either return 1 or 0, depending on whether it is expected that input_id() and parameters() contain a hashref or not
+
+    Callers    : Bio::EnsEMBL::Hive::RunnableDB::SystemCmd
+                 and Bio::EnsEMBL::Hive::RunnableDB::SqlCmd
+
+=cut
+
 sub strict_hash_format {    # This public virtual must be redefined to "return 0;" in all inheriting classes
                             # that want more flexibility for the format of parameters() or input_id()
     return 1;
 }
 
+=head2 param_init
+
+    Args       : (optional) a hash that defines Module_Defaults
+
+    Example    : $self->param_init('taxon_id' => 10090, 'source' => 'UniProt');
+
+    Description: Parses the parameters from all sources in the correct precedence order.
+                 Can be invoked explicitly with defaults, or will run implicitly before a call to param().
+
+=cut
+
 sub param_init {    # normally will run automatically on the first execution of $self->param(),
-                    # but you can enforce it by running manually, optionally supplying the default values
+                    # but you can enforce it by running explicitly, optionally supplying the default values
                     
     my $self     = shift @_;
 
@@ -56,6 +101,22 @@ sub param_init {    # normally will run automatically on the first execution of
     }
 }
 
+=head2 param
+
+    Arg [1]    : string $param_name
+
+    Arg [2]    : (optional) $param_value
+
+    Description: A getter/setter method for a job's parameters that are initialized through 4 levels of precedence (see param_init() )
+
+    Example 1  : my $source = $self->param('source'); # acting as a getter
+
+    Example 2  : $self->param('binpath', '/software/ensembl/compara');  # acting as a setter
+
+    Returntype : any Perl structure or object that you dared to store
+
+=cut
+
 sub param {
     my $self = shift @_;
 
@@ -69,6 +130,16 @@ sub param {
     return $self->{'_param_hash'}{$param_name};
 }
 
+=head2 param_substitute
+
+    Arg [1]    : string $string_with_templates
+
+    Description: Performs parameter substitution on strings that contain templates like " #param_name# followed by #another_param_name# " .
+
+    Returntype : string
+
+=cut
+
 sub param_substitute {
     my ($self, $string) = @_;
 
@@ -79,6 +150,12 @@ sub param_substitute {
 
 #--------------------------------------------[private methods]----------------------------------------------
 
+=head2 _parse_string
+    
+    Description: this is a private method that deals with parsing of parameters out of strings.
+
+=cut
+
 sub _parse_string {
     my ($self, $method) = @_;
 
@@ -97,9 +174,13 @@ sub _parse_string {
     }
 }
 
-    # Unfortunately, MetaContainer is useless for us, as we need to load all the parameters in one go
-    #
-sub _parse_meta {
+=head2 _parse_meta
+    
+    Description: this is a private method that deals with parsing of parameters out of 'meta' table.
+
+=cut
+
+sub _parse_meta {            # Unfortunately, MetaContainer is useless for us, as we need to load all the parameters in one go
     my $self = shift @_;
 
     my %meta_params_hash = ();