I have several thoughts about this subject. In particular, when writing documentation, you need to pitch it at an intended audience. Perl has two methods of documenting inline - pod and comments. These serve two different purposes, and have two different audiences. Pod is aimed at users, whereas comments are aimed at code maintainers.

When writing pod for scripts, I consider the pod to be a user guide. As such, this will include full details of command line options, environment variables, configuration options, etc. I am a fan of Pod::Usage, especially in conjunction with Getopt::Long. For Tk GUI apps, I have used Tk::Pod::Text to launch a help window, browsing the rendered pod.

Your requirements are for documenting subroutine calls and dataflows. These fall into the category of commentary rather than pod. But, it's probably better as separate standalone files rather than in-line, in which case pod is just as acceptable a format as anything - probably more so.

I don't know any existing module for spitting out such documentation automatically, but I can suggest several places to start:

• The stash %:: (or %<namespace>::) contains entries for all subs. You can get this information from the perl debugger, thus:

    DB<1> x %::
  [download]

• The module Pod::Coverage contains some code for parsing out all sub declarations from a source file.

• You might be able to catch all calls to a given sub with Hook::LexWrap

Good luck with your endeavour

---

---

Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!

Titles consisting of a single word are discouraged, and in most cases are disallowed outright.

Read Where should I post X? if you're not absolutely sure you're posting in the right place.

Please read these before you post! —

• How do I compose an effective node title?
• How do I post a question effectively?
• Markup in the Monastery

Posts may use any of the Perl Monks Approved HTML tags:

a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr

You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)

	For:		Use:
	&		&
	<		&lt;
	>		&gt;
	[		&#91;
	]		&#93;

Link using PerlMonks shortcuts! What shortcuts can I use for linking?

See Writeup Formatting Tips and other pages linked from there for more info.