what do you mean "=head1 SEE ALSO"?
Main Topics
Browse All Topics
Loading Advertisement...
Question
pod
What is the recommened/common pod format/template in practice? Of course, they will vary, but in general?
I have an example:
=pod
=head1 NAME
Debugging mod_perl Perl Internals
=head1 Description
This document explains how to debug Perl code under mod_perl.
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,corrections and patches.
=over
=item *
Stas Bekman E<lt>stas (at) stason.orgE<gt>
=back
=head1 Authors
=over
=item *
Stas Bekman E<lt>stas (at) stason.orgE<gt>
=back
Only the major authors are listed above. For contributors see the
Changes file.
=cut
This Question has been solved and asker verified All Experts Exchange premium technology solutions are available to subscription members.
Subscribe now for full access to Experts Exchange and get
Instant Access to this Solution
- Plus...
- 30 Day FREE access, no risk, no obligation
- Collaborate with the world's top tech experts
- Unlimited access to our exclusive solution database
- Never be left without tech help again
Trusted by hundreds of thousands everyday for fast, accurate and reliable tech support.
- "The time we save is the biggest benefit of Experts Exchange to Warner Bros. What could take multiple guys 2 hours or more each to find is accessed in around 15 minutes on Experts Exchange." Mike Kapnisakis, Warner Bros.
- "Our team likes having a resource that is more secure than just using Google and most experts using this service really know their stuff. It's nice to look here first versus using Google." Dayna Sellner, Lockheed Martin
- "Anytime that I've been stumped with a problem, 9 out of 10 times Experts Exchange has either the accepted solution or an open discussion of the potential solution to the problem." Kenny Red, eBay Inc.
See what Experts Exchange can do for you.
Got a question?
We've got the answer.
Experts Exchange has been collecting answers to technology questions since 1996…3 million and counting! If you have a question, chances are we already have your answer.
Need individual assistance?
Our experts are ready to help.
If you can't find the exact answer you're looking for, ask our exclusive community of 50,000 experts. You’ll get a personalized answer from a trusted professional.
Want to learn from the best?
Read articles from industry experts.
Thousands of free tech tips, tricks, how-to’s and tutorials are available in our peer reviewed articles section. See for yourself how smart our experts are, no login required.
Working on a long term project?
Store your work and research.
Save solutions to your questions, answers you’ve discovered through searching plus helpful articles in your personal knowledgebase for easy future access.
Access the answers to your technology questions today.
30-day free trial. Register in 60 seconds.
What Makes Experts Exchange Unique?
Members of the expert community talk about why the experience at Experts Exchange is different than what you will find anywhere else.
Trusted by the world's most respected brands.
Faithfully serving IT professionals since 1996.
Try it out and discover for yourself.
30-day free trial. Register in 60 seconds.
Free Tech Articles
-
WARNING: 5 Reasons why you should NEVER fix a computer for free.
It is in our nature to love the puzzle. We are obsessed. The lot of us. We love puzzles. We love the challenge. We thrive on finding the answer. We hate disarray. It bothers us deep in our soul. W...
-
SCCM OSD Basic troubleshooting
SCCM 2007 OSD is a fantastic way to deploy operating systems, however, like most things SCCM issues can sometimes be difficult to resolve due to the sheer volume of logs to sift through and the dispe...
-
Migrate Small Business Server 2003 to Exchange 2010 and Windows 2008 R2
This guide is intended to provide step by step instructions on how to migrate from Small Business Server 2003 to Windows 2008 R2 with Exchange 2010. For this migration to work you will need the fo...
-
Create a Win7 Gadget
This article shows you how to create a simple "Gadget" -- a sort of mini-application supported by Windows 7 and Vista. Gadgets can be dropped anywhere on the desktop to provide instant information, ...
-
Outlook continually prompting for username and password
There have been a lot of questions recently regarding Outlook prompting for a username and password whilst using Exchange 2007. There are a few reasons why this would happen and I will try to cover t...
-
Backup Exchange 2010 Information Store using Windows Backup
There seems to be quite a lot of confusion around the ability to backup Exchange 2010 using the built in Windows Backup feature. This stems from the omission of this feature prior to Exchange 2007 s...
Cloud Class Webinars
- Avoiding Bugs in Microsoft Access
Alison Balter takes and in-depth look at avoiding bugs in Access. In this webinar you will learn about using the immediate window to debug your applications, invoking the debugger, using breakpoints to troubleshoot, stepping through code, setting the next statement to execute, ...
- Top 10 Best New Features in Visio 2010
Scott Helmers gives live demonstrations of the top 10 new features in Visio 2010. This webinar will teach you how to create compelling diagrams by adding shapes to the page with a single click, linking the shapes in a diagram to data in Excel (or SQL Server, or SharePoint), ...
- IT Consultant Business Secrets Revealed
Michael Munger, Experts Exchange tech pro and IT consultant, pulls back the curtain on his very successful businesses and answers question on every IT consultant and business owner should know about. He shares secrets on what he did to solve the 5 most common problems in IT, ...
- Disaster Recovery and Business Continuity
Quest CTO, Mike Billon, gives an overview of the steps involved in building a dunamic disaster recovery plan. Through case studies and an examination of software/hardware tooles for monitoring and testing, you'll gain a better understandin of where you are, where you want ...
- Organize Your Visio Diagrams with Containers and Lists
Scott Helmers uses cross functional flowcharts, wireframe diagrams, data graphic legends and seating charts to teach you: how to ustilize all three new structured diagram components in Visio 2010, the best practices for organizeing shapes in previous version of Visio, how to organize ...
- How to Us Objects, Properties, Events and Methods in Microsoft Access
Alison Dalter gives an in-depbth look at objects, properties, events and methods in Microsoft Access. In this webinar you will learn about using the object browser, referring to objects, working with properties and methods, working with object variables, understanding the ...
Join the Community
Give a Little. Get a Lot.
Join the community of experts here and help other tech pros by answering question in your area of expertise. You can earn FREE access to all Experts Exchange's premium features and resources.
Answers
"=head1 SEE ALSO" can be used to point people to code that's similar to yours, or code that your code builds on. For example, if you extended a module called "Module::Foo", you'd put that module in the "=head1 SEE ALSO" section. Helps to give people some background.
POD is good for having multi-line comments too, similar to the /* */ structure in C. If you want to comment out an entire chunk of code, instead of putting a # before each line (which is tedious), you could put "=head1 COMMENT" at the beginning and "=cut" at the end.
There are also programs out there that'll transform POD into HTML or other formats for easy reading and dissemination.
POD and comment lines are sort of orthogonal. POD is supposed to be the external documentation for your code. It says what your code does. Comment lines are internal documentation. They say how your code does what it does. There's a difference there, really.
For example, you might have a method that takes two matrices and multiplies them. Your POD would say pretty much just that, "takes two matrices and multiplies them." Your comment lines would comment your code for the various steps along the way. I'd imagine comments such as "set up a loop to run along matrix A columns" or "initialize the output matrix". The external user doesn't need to know the nitty-gritty of how you multiply the matrices, only that you do so, but someone maintaining your code (you, perhaps, six months down the line) needs to know that nitty-gritty for debugging purposes.
Gurus, wonderful explanations. I googled but couldn’t find a good one showing examples for documenting classes, methods, attributes, arguments, inheritance, overload, etc. Documentation is always critical, and I’d like to have a decent example that can be “popularly” used in practice. Please recommend the examples for classes, methods, attributes, arguments, inheritance, overload, etc.
jl
The best way would be to copy the style of some authors who are especially good at it. Take a look at some of Damian Conway's modules to see his POD style; it's usually really good. You could definitely do worse than emulating his POD style.
Also, just go through CPAN (www.cpan.org) to see various other styles of POD.
I'd like to point out that you want to keep your documentation template as light as possible. Otherwise it won't be used anymore, because it contains too many sections that may not be relevant to every module. Using one that is pretty much standard on CPAN gives you just enough structure to be useful, but gives the documentor enough freedom to do what he likes. Remember that developers hate having to document; don't overburden them.
3 Ways to Join
Business Accounts
- Perfect for organizations
- Multiple users
- Save over 36%
- Create a Business Account
Answer for Membership
- Earn free access
- Showcase your knowledge
- No credit card required
- Sign Up to Answer
Loading Advertisement...
by: kanduraPosted on 2005-11-01 at 10:04:54ID: 15202012
I generally use the format that Module::Starter gives you. That's roughly:
=head1 NAME
=head1 VERSION
=head1 SYNOPSIS
=head1 DESCRIPTION
=head1 FUNCTIONS or METHODS or EXPORTS
=head1 AUTHORS
=head1 BUGS
=head1 SEE ALSO
=head1 COPYRIGHT & LICENSE