Beefy Boxes and Bandwidth Generously Provided by pair Networks
more useful options
 
PerlMonks  

Crash Course in POD

by jens (Pilgrim)
on Sep 25, 2002 at 00:29 UTC ( #200514=perlquestion: print w/ replies, xml ) Need Help??
jens has asked for the wisdom of the Perl Monks concerning the following question:

I've just been contracted for a few weeks (or more) to document a messy 20,000 lines of Perl code. The code base itself, by the sounds of it, is a hack on a hack on a hack on a prototype that never got thrown away. Worse, the programmer who's been maintaing and extending it for the last year or so is Chinese and speaks/writes English poorly, meaning that the existing documentation isn't very useful.

Thus, the need for documentation.

The question: I've never used POD before. But I suspect that's the best way to approach this--POD everything and then accumulate that into a Programmer's Manual. I've tried 'perldoc perldoc' but that wasn't very helpful--where can I find out more about creating POD? Also, there's several dozen scripts, each of which could have it's own perldoc--but it's probably better to merge them all into a single text document. How do I do this?

the other question: This is, in a way, the documentation project from hell. Does anyone else have similar experiences with documentating big chunks of messy, obfu codes years after it's been written--and when it's in production?

Any thoughts on this would be much appreciated.

--
Microsoft delendum est.

Comment on Crash Course in POD
Re: Crash Course in POD
by Zaxo (Archbishop) on Sep 25, 2002 at 00:43 UTC
    See perlpod and perlpodspec. You will probably find it very easy going. If pod is flexible enough for your needs, great!.

    Also 'h2xs -AXn Foo' will give you a pod skeleton for manpage style, in Foo/Foo.pm.

    After Compline,
    Zaxo

Re: Crash Course in POD
by jarich (Curate) on Sep 25, 2002 at 00:53 UTC
    Learning about POD
    Try perldoc perlpod for the POD man page.

    Single point of documentation
    Remember that single text documents tend to vanish leaving the new maintainer/developer unaware of all the hassle you went though. I'd write the POD into all the scripts and then copy the useful bits into a separate file. It's more work, but it'll be more useful to the next coder.

    Documenting a large project
    As to your last question. DON'T TOUCH THE CODE! Yes, documenting is a pain, and boring and I'm sure you can see 1001 ways to make the code a little clearer but if you're not being paid to fix the code and it's in production, don't touch it. It works (presumably), leave it alone.

    Just go in, test away, work out what it does, try to guess how it does it, and document what you can understand. It's (probably) okay to put stuff like:

    ##### Warning: through inspection, it appears that the ##### following code may fail under these circumstances: # A) ..... # B) ..... # C) ..... ##### A possible solution is in the following (untested) ##### code: # ......... # .........
    but remember what you're being paid to do. Adding documentation to a program should never alter it's functionality. (Well, unless you're playing with Damian's selfgol).

    If you feel that something really ought to be changed, write it down and bring it up with your supervisor after the documentation project has been completed. Don't allow yourself to be pressured into making functional changes at the same time as you're making formatting/documentation changes. Something will go wrong and your documentation will get blamed.

    Oh, and use CVS. Or some other revision control system. And check your changes in regularly, although probably on a code branch and not directly into the main tree.

    Lastly:
    Good luck!

    Hope it helps.

    jarich

      Single point of documentation
      <snip>... I'd write the POD into all the scripts and then copy the useful bits into a separate file. It's more work, but it'll be more useful to the next coder.


      Having a single point of documentation is one of the most important reasons I want to use POD--that way a change to the commented source is immediately reflected in the Programmer's Manual.

      But when you say to "copy the useful bits into a separate file" this doesn't solve the problem.

      Is there a way, in POD, to accumulate POD comments in multiple files into one larger document? This way there would truly be a single point of documentation.

      --
      Microsoft delendum est.
        Is there a way, in POD, to accumulate POD comments in multiple files into one larger document? This way there would truly be a single point of documentation.

        There is no way in POD, but there are many ways in Perl (at least, there is more than one way...) Go to http://www.cpan.org/modules/01modules.index.html and you will find more than 30 modules dealing with POD. In your case, maybe Pod-Simple or Pod-Parser is what you need.

        With either module, extract the POD from each file and copy it to the result file. That's simple.

Re: Crash Course in POD
by PodMaster (Abbot) on Sep 25, 2002 at 08:23 UTC
    The other fella have pointed you to the meat of the subject (perlpod and perlpodspec), and I'd like to point you to Pod::Tree (watchout for pod2html being overwritten, edit the makefile and don't install any of the scripts, they're interdependent, and will install the missing ones) and Pod::Html (fyi: i like Pod::Simple very much, as well as ActivePerl::DocTools).

    Nobody reads pod in pod format.

    Pod is best kept with the sourcecode, that way synchronization doesn't become a problem. If the pod is staring you in the face, at the same time as the sourcecode, it's hard to ignore mismatches ;)

    Any stuff you put in external pod files (.pod) should be tutorial like material (extended documentation) ~ the api spec should be in with the module (.pm )

    Aside from that, don't get fancy with the pod (avoid =begin exoticFormat , bah!). Keep it simple.

    Here are a few modules with pod that I wrote ;)

    HTML::LinkExtractor ~ a good pod example. I most like to read pod produced by Pod::Html, cause it makes a nice TOC at the top (like you can see there).

    If you look at the source, you'll see that the pod is at the __END__. Since this was a very short module, it makes little difference, but for bigger modules, it will definetly be harder to manage __END__ pod, so you'll wanna use inline pod , like:


     

    Now that is gravy right there ;)(that's the way i'd lay it out). It is important to remember not to document methods that the user of your module should not be calling directly. Use #c#o#m#m#e#n#t#s# for those.

    Pod::Stripper ~ a bad example, mostly cause they're test cases ;)(deep pod voodoo, cause perl's idea of pod is different ~ perlpod/perlsyn explains)

    ____________________________________________________
    ** The Third rule of perl club is a statement of fact: pod is sexy.

      It is important to remember not to document methods that the user of your module should not be calling directly. Use #c#o#m#m#e#n#t#s# for those.
      Or you can steal Larry's own trick used while writing Camel III (which was done in POD): he "hid" little notes to self by using =for later. Or in this case, one might use =for internal use only. I prefer this over comments for two reasons. It is still accessible to POD tools if so chosen and can be extracted/marked up for an extended documentation. Secondly, it is a clear signal to human readers, more so than just mere comments.

      Makeshifts last the longest.

        IIRC, the Camel wasn't written in POD. It was written in POD + extensions, to be processed by a special pod2ora program. I've the "POD"s of the second edition of the Cookbook here - if you run it through pod2text, you'll get quite some warnings about unrecognized markup.

        Personally, I would use POD if the intended end result was man pages. I'd use LaTeX if the end result is intended to be a document of some form.

        Abigail

      Nobody reads pod in pod format.

      Very not true.

      Most recent example is merlyn's article draft he refered to in the chatterbox. It was written in POD, but I doubt anyone has converted it to another format prior to reading it. And why would you convert it? If you understand POD, which is very easy, POD is perfectly readable (unlike some other documentation formats, xml based ones imho being the worst).

      so you'll wanna use inline pod

      No, I absolutely do NOT want that. And whenever I encounter code that does interleave pod with code, I podselect it and put it at the end instead. See also [style, *again

      # I try not to put an __END__ token here cause mod_perl

      You probably mean Apache::Registry, which is not the same as mod_perl. With mod_perl, you usually use a module with a handler in it, just like Apache::Registry itself. Please note that Apache::Registry has an __END__ token in it and works just fine.

      Juerd
      - http://juerd.nl/
      - spamcollector_perlmonks@juerd.nl (do not use).
      

        Monk please.

        merlyn is always asking for somebody to proofread his articles -- any time I help him out I most definetly use (podchecker and) pod2html before reading them.

        Yeah, inline pod is a personal style thing. I used to be like you, not liking inline pod, but now I feel its the way to go (tastes change).

        And as for mod_perl, yup, I guess I should've added cause like %80 of my dealing with mod_perl are with Apache::Registry (and alikes), so I don't assume like i'm writing some handler (I assume Registry).

        update: added like i'm writing -- besides, Registry is the handler I'm aiming for, not just some handler.


        MJD says you can't just make shit up and expect the computer to know what you mean, retardo!
        I run a Win32 PPM repository for perl 5.6x+5.8x. I take requests.
        ** The Third rule of perl club is a statement of fact: pod is sexy.

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://200514]
Approved by jarich
Front-paged by broquaint
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others lurking in the Monastery: (6)
As of 2014-09-02 02:05 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    My favorite cookbook is:










    Results (18 votes), past polls