Let me get this straight: you've been assigned to document a system you don't already understand, in a language you're not proficient in? :-( :-(

With no disrepect to you, this sounds like a bad idea: it's like asking a man who speaks only Japanese to write English documentation using a Japanese-English dictionary. The end results are unlikely to be great; and it's not a fair task to ask for the documentation writer. You might asking telling your boss, politely, to find a better use for your time and energy.

That said, if your boss is dead set on making you do this work, there's no one single tool that will help out. Perl has many, many ways to accomplish any given task (by design, perl's motto is "There's More Than One Way To Do It"). This means it's typically very hard to pin down what's actually being done; you have to check every single way someone might have done something to find out whether or not that thing has happened.

There's no good way to document the list of arguments to a perl function, because perl lets you pass nearly anything into a function. For example, perl functions can take a list of arguments (of any length), and return a list of arguments (of any length). The arguments may or may not even have names. Some functions even do different things depending on the number or types of the arguments you give them. The best way to document arguments, is, unfortunately, to read the code, and find all the places @_, $_ <something> , or "shift" is used.

As for tracing program flow, again, it's complicated. There are a *LOT* of ways to transfer program flow control, and a lot of valid syntaxes for calling functions. There are normal function calls, method calls, calling code references, AUTOLOADED functions, functions created using the "*FOO{thing}" syntax, gotos and strings evaluated at run time. Then there's perl XS, which links Perl to other languages. There's die() which terminates a program, except if you're calling it from an 'eval' statement, or if you've got the __DIE__ signal handler set. There's the tie() command, which calls certain subroutines every time a tied variable is accessed. And so on...

Perl sometimes can't even figure out what some of these calls will do until it encounters them; the "eval" function, for example, will attempt to execute the contents of a given variable as if it contained valid perl code.

That said, if you *just* have a list of subroutines that call other subroutines, you could try taking the output from B::Xref, and organizing it into a call tree. That's what I did: but the copyright for that code belongs to my company, so I can't post it for you. :-( *sigh* ( Lesson: Never do cool stuff at work, no matter how handy the tool may seem. :-() Otherwise, someone else will own the cool stuff, and it will be illegal for you to recreate it :-().

If that sounds too hard, then just grit your teeth, and read the code as best you can. :-( Good luck! It sounds like you've been saddled with quite an unfair job; I've got several years of perl experience, and I'm still getting headaches untangling my ex-boss's hairy code. 8,000 lines of code without a subroutine in sight! :-( In your case, pray that the person writing the code was good at it, (unlikely, because good perl is documented perl), or that they were very basic, so that they're not trying to be "tricky" all the time. (*grumble* Stupid nested map/grep/conditional/postscript if debug statements with *no* indentation! ) :-(

--
Ytrew Q. Uiop