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