[Omaha.pm] RE: Model::Common and Model::DataTypes perldoc added

Jay Hannah jhannah at omnihotels.com
Wed Aug 18 15:38:29 CDT 2004


In vi ":set list" of your POD shows this:

$
=head2 is_iata_num$
 $
  This method validates a provided iata number using our $
  Model::omares::Prod::omtamst table$
 $
  Usage: $self->is_iata_num("12345678");$
$
=cut $
sub is_iata_num {$

This is bad mojo.
1) Regular sentences in POD should not be indented with spaces. 2+ space indention in POD is special. It indicates that the text cannot line wrap (e.g.: source code). Non-indented text is handly in POD as POD intepreters will auto re-wrap short and long lines automatically, just like web browsers wrap HTML. Additionally, in HTMLified POD non-indented text is printed in (normal) variable width font and indented text is displayed in fixed width font. So indention of your short Usage: example is cool, but the sentence describing what it does should not be indented.
2) The line immediately after the =head2 line contains a space. That's bad. That indicates that the =head2 is not over yet. So, in HTMLified POD, the entire description ends up wrapped in <h2></h2> tags, which is ugly.

So, the block above should look like this instead:

$
=head2 is_iata_num$
$
This method validates a provided iata number using our $
Model::omares::Prod::omtamst table$
$
  Usage: $self->is_iata_num("12345678");$
$
=cut $
sub is_iata_num {$

which is pretty in HTML. I committed the changes. They're all pretty now. -grin-

   http://razorbill/~jhannah/MVC/Model/Common.html

   http://razorbill/~jhannah/MVC/Model/DataTypes.html

 
j




  -----Original Message-----
  From: Sean Baker [mailto:pbaker at omnihotels.com]
  Sent: Wednesday, August 18, 2004 5:18 AM
  To: jhannah at omnihotels.com
  Subject: RE: Model::Common and Model::DataTypes perldoc added


  I'm using

   

  =head2 method_name

   

  =cut

   

  Wrong?

   

  Sean Baker

  Software Architect

  Omni Hotels

  (402) 952-6508

  pbaker at omnihotels.com

   

   

  Find out why we believe the Lone Star State is even more ideal this summer and about the Ideal Escape leisure package. Call 1-800-The-Omni or visit us at www.omnitexashotels.com

   


------------------------------------------------------------------------------

  From: Jay Hannah [mailto:jhannah at omnihotels.com] 
  Sent: Tuesday, August 17, 2004 3:06 PM
  To: pbaker at omnihotels.com
  Subject: RE: Model::Common and Model::DataTypes perldoc added

   

   

  Weird glitches in how you're doing POD?

   

     http://razorbill/~jhannah/MVC/Model/Common.html

     http://razorbill/~jhannah/MVC/Model/DataTypes.html

   

  j

   

   

    -----Original Message-----
    From: Sean Baker [mailto:pbaker at omnihotels.com]
    Sent: Monday, July 26, 2004 9:40 AM
    To: resmis at omnihotels.com
    Subject: Model::Common and Model::DataTypes perldoc added

    I've added perldoc to our two most important Core Model classes, Common and DataTypes.

     

    You can read it by going to Omni::MVC::Model and typing "perldoc Common" or "perldoc DataTypes".

     

    http://cvs/source/MVC/Model/Common.pm

    http://cvs/source/MVC/Model/DataTypes.pm

     

    Sean Baker

    Software Architect

    Omni Hotels

    (402) 952-6508

    pbaker at omnihotels.com

     

     

    Find out why we believe the Lone Star State is even more ideal this summer and about the Ideal Escape leisure package. Call 1-800-The-Omni or visit us at www.omnitexashotels.com

     
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.pm.org/pipermail/omaha-pm/attachments/20040818/c4348fc1/attachment.htm


More information about the Omaha-pm mailing list