Documenting a Module

jlongino has asked for the wisdom of the Perl Monks concerning the following question:

I'm currently working on a module and have most of the coding finished. One area I'm not sure about is whether or not I should put required "use" statements in the module or should the documentation specify that the end user add the appropriate ones in their program?

The next step is embedding module documentation but, having never done this (embedding it in the module) before, I could use some advice.

I searched a bit on this site, but received too many hits and was unable to narrow the keywords down. I noticed c's post Call for (gentle) critique. and think that it would serve as an excellent example to use as a template. Is there anything in addition to this example that I should add?

If anyone can point me to other good documentation on the subject, I would appreciate it greatly.

@a=split??,'just lose the ego and get involved!';
for(split??,'afqtw{|~'){print $a[ord($_)-97]}

Comment on Documenting a Module

Replies are listed 'Best First'.
Re: Documenting a Module by dragonchild (Archbishop) on Sep 01, 2001 at 00:40 UTC
There are two ways that your module could be using another module. It directly uses that modules functionality, like Carp or CGI or Exporter. This could either be through function calls or an @ISA relationship. It is passed an object of a given class. In the first case, where a user of your module would expect that this given functionality be there automatically, then I would put a use in your module and document that your module depends on other modules being installed. In the second case, I would not do a use on that module, because you're not actually instantiating that object, but are being given the object. The use has to have already been done for the object to be given to you. Your initial questions on POD can be answered at perlpod and by reading a number of the submissions in the Code Catacombs. I'd also like to commend you for actually taking the time to consider these issues. ++! ------ We are the carpenters and bricklayers of the Information Age. Vote paco for President!	[reply]
Re: Documenting a Module by tachyon (Chancellor) on Sep 01, 2001 at 00:57 UTC
Have a look at perlman:perlxstut and particularly h2xs. If you run `h2xs -X MyModule` then you will get a directory called MyModule with five files in it. The MyModule.pm has stubs for the standard documentation. The others you may recognise from any other standard module distribution. `C:\>h2xs -X MyModule Writing MyModule/MyModule.pm Writing MyModule/Makefile.PL Writing MyModule/test.pl Writing MyModule/Changes Writing MyModule/MANIFEST C:\>` [download] cheers tachyon s&&rsenoyhcatreve&&&s&n.+t&"$'$`$\"$\&"&ee&&y&srve&&d&&print	[reply] [d/l]
Re: Documenting a Module by Masem (Monsignor) on Sep 01, 2001 at 00:38 UTC
Perl module document embedding is described in perlpod (Plain Old Documentation). For starting points, you can look at any module that's probably included with perl to get an idea of what goes where. Of late, one consideration is between putting all the module documentation in one block (typically at the end), or in separate blocks, such that function calls have their documentation right next to them. To perldoc, this makes no difference, but it all depends on your programming style and how you comment functions. ----------------------------------------------------- Dr. Michael K. Neylon - mneylon-pm@masemware.com \|\| "You've left the lens cap of your mind on again, Pinky" - The Brain It's not what you know, but knowing how to find it if you don't know that's important	[reply]