Beefy Boxes and Bandwidth Generously Provided by pair Networks
Welcome to the Monastery
 
PerlMonks  

Re: Worst thing you ever made with Perl

by jonadab (Parson)
on Sep 29, 2003 at 14:03 UTC ( #294959=note: print w/replies, xml ) Need Help??


in reply to Re: Worst thing you ever made with Perl
in thread Worst thing you ever made with Perl

Speaking of POD... up until now, I've been just using comments, as I would in any other language. Is there a very simple tutorial I could pick up someplace that would show me how to write my comments as POD, in a fashion that would be mostly transparent during coding but potentially useful later on? POD has been on my to-learn list for a few months now... maybe it's time to pick it up...


$;=sub{$/};@;=map{my($a,$b)=($_,$;);$;=sub{$a.$b->()}} split//,".rekcah lreP rehtona tsuJ";$\=$ ;->();print$/

Replies are listed 'Best First'.
Re: Re: Worst thing you ever made with Perl
by barrd (Canon) on Sep 29, 2003 at 14:13 UTC
    Hiya jonadab,
    Here's a quick online POD page link (which I printed off and stuck to my wall as a reference tool).

    As for POD coding style, that's something you'll have to develop yourself.

    HTH

Re: Re: Worst thing you ever made with Perl
by Juerd (Abbot) on Sep 30, 2003 at 06:39 UTC

      Both of these tutorials, nice though they may be, talk mainly about how to stick one big block of documentation at the top or bottom of the whole file. For me that would be a step backwards. I'm MUCH more interested in documenting each function locally, right near the top of that function, (usually, right below the line that pulls @_ into named lexicals) like I would do with comments. I've been led to believe this is possible with POD, which is why I asked. Doing it this way makes it easier to compare the documentation of what the function does with the function itself, which makes for easier maintenance. Yes, I know I can split my window in Emacs and put the doc in one half and the code in the other, but a lot of times I like to put two sections of code in the two halves, and when I start splitting vertically into three parts, I find that it puts too much crimp on how many lines I can see at once. Maybe what I really need is a larger monitor, but until then, I'd like to keep the docs for each function together with that function.


      $;=sub{$/};@;=map{my($a,$b)=($_,$;);$;=sub{$a.$b->()}} split//,".rekcah lreP rehtona tsuJ";$\=$ ;->();print$/
        ... talk mainly about how to stick one big block of documentation at the top or bottom of the whole file...
        That's one way of doing it (or looking at it) I guess, but what's to stop you from adding multiple blocks of POD?
        #!/usr/bin/perl -w use strict; # codage... =head1 NAME doStuff function =head1 DESCRIPTION This sub is designed blah de blah blah and on and on etc ad infinitum =cut sub doStuff { # code for sub } # codage... =head1 NAME What the next line does =head1 DESCRIPTION This line uses some funky techniques I picked up from PM and does the following... =cut # insert incredibly funky bit of perl code here # carry on coding...
        HTH, if not lemme know and I'll try to anser any more q's you have

        Both of these tutorials, nice though they may be, talk mainly about how to stick one big block of documentation at the top or bottom of the whole file. For me that would be a step backwards. I'm MUCH more interested in documenting each function locally, right near the top of that function, (usually, right below the line that pulls @_ into named lexicals) like I would do with comments.

        That is exactly the same. You return to code with =cut. An example:

        I hate maintaining code that is interrupted by documentation. I prefer updating the code first, documentation later. Otherwise, I'd probably end up putting tests, real code and documentation all in one place. Awful.

        Juerd # { site => 'juerd.nl', plp_site => 'plp.juerd.nl', do_not_use => 'spamtrap' }

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://294959]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others having an uproarious good time at the Monastery: (4)
As of 2021-03-01 04:35 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found

    Notices?