anirudh.agarwal has asked for the wisdom of the Perl Monks concerning the following question:

Hi Monks, I have an issue with the documentation. I tried to add documentation for a new function, stop() added in the file. Originally, the documentation was as below 
=head1 FUNCTIONS

No subroutines are exported.

=over

=item run()
this will run this script
=back

=cut

[download]
I tried adding it in the following way 
=head1 FUNCTIONS

No subroutines are exported.

=over

=item run()
this will run this script
=back

=item stop()
this will stop this script
=back
=cut

[download]
But the above doesnt work. I dont understand what went wrong and how do I correct it. Please help. Thanks :)

Replies are listed 'Best First'.
Re: Documentaion with multiple functions
by hippo (Archbishop) on Dec 18, 2013 at 13:50 UTC

    You have one over and two backs. Did you read the POD documentation perlpod?

[reply]
[d/l]
[select]
Re: Documentaion with multiple functions
by taint (Chaplain) on Dec 18, 2013 at 13:59 UTC
    Do take hippo's advice. Else you'll never understand.

    I might also point out missing spaces. Typically, areas between markers are double spaced. 

    =head1 FUNCTIONS

No subroutines are exported.

=over

=item run()

this will run this script

=item stop()

this will stop this script

=back

=cut

    [download]
    Now go read perlpod! :)

    --Chris

    UPDATE -- posted incorrect link for pod docs 
    Yes. What say about me, is true.
[reply]
[d/l]
Re: Documentaion with multiple functions (perl=pod whitespace isn't optional)
by Anonymous Monk on Dec 18, 2013 at 22:18 UTC
    You're not alone :) see Re^5: POD translation to HTML bug? (pod2html Pod::Html 1.11) pod likes the whitespace , it needs the whitespace, the whitespace isn't optional, because 
    
=item * item title
still item title
and still item title
and still item title
and still item title
and still item title

NOW CONTENTS FOR THIS item title no longer item title
still contents

=cut

    [download]
    Is like equivalent to 
    =item * item title still item title and still item title and still ite
+m title and still item title and still item title

NOW CONTENTS FOR THIS item title no longer item title still contents

=cut

    [download]
    in pod whitespace seperates paragraphs, commands (like =item * title) from content
[reply]
[d/l]
[select]
Re: Documentaion with multiple functions
by Anonymous Monk on Dec 18, 2013 at 14:14 UTC
    pod is far more unforgiving than you might expect, and when it does not like what it sees it often produces ... nothing.
[reply]
      There's a Module for that -- Pod::Checker.

      --Chris

      Yes. What say about me, is true.
[reply]
[reply]

Back to Seekers of Perl Wisdom