perldocs added

modules/Bio/EnsEMBL/Hive/Utils.pm

-package Bio::EnsEMBL::Hive::Utils;
+
+=pod
 
 =head1 NAME
 
 Bio::EnsEMBL::Hive::Utils
 
-=head1 DESCRIPTION
-
-Let's keep here various utility functions that are not proper Extensions (do not cunningly extend other classes)
+=head1 SYNOPSIS
 
-You can either inherit from this package, call the functions directly or import:
+        # Example of an import:
+    use Bio::EnsEMBL::Hive::Utils 'stringify';
+    my $input_id_string = stringify($input_id_hash);
 
+        # Example of inheritance:
+    use base ('Bio::EnsEMBL::Hive::Utils', ...);
+    my $input_id_string = $self->stringify($input_id_hash);
 
-=head1 Example of inheritance:
+        # Example of a direct call:
+    use Bio::EnsEMBL::Hive::Utils;
+    my $input_id_string = Bio::EnsEMBL::Hive::Utils::stringify($input_id_hash);
 
-use base ('Bio::EnsEMBL::Hive::Utils', ...);
-
-my $input_id_string = $self->stringify($input_id_hash);
+=head1 DESCRIPTION
 
+This module provides general utility functions (at the moment of documentation, 'stringify' and 'destringify')
+that can be used in different contexts using three different calling mechanisms:
 
+    * import:  another module/script can selectively import methods from this module into its namespace
 
-=head1 Example of a direct call:
+    * inheritance:  another module can inherit from this one and so implicitly acquire the methods into its namespace
+    
+    * direct call to a module's method:  another module/script can directly call a method from this module prefixed with this module's name
 
-use Bio::EnsEMBL::Hive::Utils;
+=head1 CONTACT
 
-my $input_id_string = Bio::EnsEMBL::Hive::Utils::stringify($input_id_hash);
+  Please contact ehive-users@ebi.ac.uk mailing list with questions/suggestions.
+  
+=cut
 
 
+package Bio::EnsEMBL::Hive::Utils;
 
-=head1 Example of import:
+use strict;
+use warnings;
+use Data::Dumper;
 
-use Bio::EnsEMBL::Hive::Utils 'stringify';
+use Exporter 'import';
+our @EXPORT_OK = qw( stringify destringify );
 
-my $input_id_string = stringify($input_id_hash);
 
+=head2 stringify
 
-=head1 Author
+    Description: This function takes in a Perl data structure and stringifies it using specific configuration
+                 that allows us to store/recreate this data structure according to our specific storage/communication requirements.
 
-Leo Gordon, lg4@ebi.ac.uk
+    Callers    : Bio::EnsEMBL::Hive::DBSQL::AnalysisJobAdaptor      # stringification of input_id() hash
+                 Bio::EnsEMBL::Hive::PipeConfig::HiveGeneric_conf   # stringification of parameters() hash
 
 =cut
 
-use strict;
-use warnings;
-use Data::Dumper;
-
-use Exporter 'import';
-our @EXPORT_OK = qw( stringify destringify );
-
 sub stringify {
     my $structure = pop @_;
 
@@ -59,7 +69,18 @@ sub stringify {
     return Dumper($structure);
 }
 
-sub destringify {       # eval if it seems to be a perl hash/array/string and leave intact otherwise
+=head2 destringify
+
+    Description: This function takes in a string that may or may not contain a stingified Perl structure.
+                 If it seems to contain a hash/array/quoted_string, the contents is evaluated, otherwise it is returned "as is".
+                 This function is mainly used to read values from 'meta' table that may represent Perl structures, but generally don't have to.
+
+    Callers    : Bio::EnsEMBL::Hive::ProcessWithParams              # destringification of general 'meta' params
+                 beekeeper.pl script                                # destringification of the 'pipeline_name' meta param
+
+=cut
+
+sub destringify {
     my $value = pop @_;
 
     if($value) {