is there a tool out there similar to Javadoc or POD for shell scripting? thanks
EDIT: I am not looking for existing shell man pages - there is a lot of ksh/bash code we write/support, so I was looking for a nice way to communicate what's happening, whether there is a potential for code reuse, etc. all things Javadocs are good for.
In that Javadoc generates documentation from comments in the source code, no--nothing like that exists.
However, the shell commands should all have man pages. Open a second window and use it for browsing man pages.
This is one of those cases where books are still really handy as well.
You can browse the entire Linux man pages online here.
They also provide a downloadable tarball of the man pages. With a suitable script, you should be able to reformat this anyway you wish... that's what many of the online man page reference sites do, I believe.
Apple's HeaderDoc can be used to document a variety of languages, including shell scripts. It's most commonly used for Objective-C code, but don't let that put you off using it for other languages.
HeaderDoc is an open-source project, and as such can run on other (non-Mac) operating systems. You can download it from Apple but may need to sign in for an Apple ID to access it. It's available under the Apple Public Source License.