Search code examples
perlformatindentationperldocperl-pod

How to document parameters in Perl POD


I have this POD:

=head1 My code

=head2 check

Checks something. 

Parameters:

=over 8

=item what to check.

=back

=cut

podchecker doesn't complain. perldoc shows this:

My code
  check
    Checks something.

    Parameters:

    what to check.

I expected the "what to check" line to be indented further.

How do I need to change my POD to show parameters indented? Is there a better way to do this than with =items?


Solution

  • Both perldoc and pod2html ignore the indentlevel. Use bullets as a workaround. See an example below.

    =head1 My code
    
    =head2 check with no bullets or numbers
    
    Checks something. 
    
    Parameters:
    
    =over
    
    =item what to check A
    
    =item what to check B
    
    =back
    
    =head2 check with bullets
    
    Checks something. 
    
    =over
    
    =item * what to check A
    
    =item * what to check B
    
    =back
    
    =head2 check with numbers
    
    Checks something. 
    
    =over
    
    =item 1. what to check A
    
    =item 2. what to check B
    
    =back
    
    =cut
    
    

    Running perldoc /path/to/script.pl results in this:

    My code
       check with no bullets or numbers
           Checks something.
    
           Parameters:
    
           what to check A
           what to check B
    
       check with bullets
           Checks something.
    
           o   what to check A
    
           o   what to check B
    
       check with numbers
           Checks something.
    
           1. what to check A
           2. what to check B
    

    REFERENCES:

    The indentlevel option to "=over" indicates how far over to indent, generally in ems (where one em is the width of an "M" in the document's base font) or roughly comparable units; if there is no indentlevel option, it defaults to four. (And some formatters may just ignore whatever indentlevel you provide.)

    (From perldoc perlpod, boldface mine)