[Bioperl-l] POD nitpicking

[Heikki Lehvaslaiho]

Cleaning the POD documentation for the next release, I ran into a few new
common problems. The following text snippet demonstrates the problems. The
first sections shows the warnings and errors within the text and the next
section shows the cleaned code:


### cut ##############################################################
# two warnings and one error generated

=head2 Group of methods

=head2 my_method

 #*** WARNING: empty section in previous paragraph at line 6 in file tmp/t
   Title   : 
   Usage   : 
   Function: 
   Returns : 
   Args    : 
   Status  : 

The my_method ... which isn\'t set. (Note that \ is displayed)

=cut
#'
#*** ERROR: Spurious text after =cut at line 18 in file tmp/t
sub my_method {

}

######################################################################
# no warnings 

=head2 Group of methods2

=cut

=head2 my_method2

   Title   : 
   Usage   : 
   Function: 
   Returns : 
   Args    : 
   Status  : 

The my_method ... which isn't set.

=cut

#'
sub my_method2 {

}
### cut ##############################################################

I was using perl 5.6.1 and 'podchecker --warnings --warnings'.

Lessons learned:

1. Sections starting =head should not be empty. End empty sections 
   with =cut
2. Escaping single quotes with backlash is not a good idea. Instead, 
   put #' after the POD section. Remember to leave an 
   empty line after =cut.



There is a problem accessing the wiki pages. so these recommendations not
there, yet.

	-Heikki

-- 
______ _/      _/_____________________________________________________
      _/      _/                      http://www.ebi.ac.uk/mutations/
     _/  _/  _/  Heikki Lehvaslaiho          heikki@ebi.ac.uk
    _/_/_/_/_/  EMBL Outstation, European Bioinformatics Institute
   _/  _/  _/  Wellcome Trust Genome Campus, Hinxton
  _/  _/  _/  Cambs. CB10 1SD, United Kingdom
     _/      Phone: +44 (0)1223 494 644   FAX: +44 (0)1223 494 468
___ _/_/_/_/_/________________________________________________________