Do you know where your variables are? | |
PerlMonks |
comment on |
( [id://3333]=superdoc: print w/replies, xml ) | Need Help?? |
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:
Good luck with your endeavour -- In reply to Re: Documenting Perl Scripts
by rinceWind
|
|