JavaDoc like framework for shell scripts? [closed]

Question

Is there an open source or public domain framework that can document shell scripts similar to what JavaDoc produces? I don't need to limit this just to a specific flavor of shell script, ideally I would like a generic framework for documenting API or command line type commands on a web page that is easy to extend or even better is self documenting.

Answer 1

If you have Perl, here is an example of someone who used Perl's POD system for documentation of a shell script.

The trick is to have the Perl POD section in a bash "Here-Document", right after the null command (no-op) :.

• Start with : <<=cut
• Write your POD-formatted man page
• That's it. Your POD ends with =cut, which has also been defined as the end of the shell Here-doc

Your script can then be processed with all the usual Perl tools like perldoc, or perl2html, and you can even generate real man pages with pod2man.

As an example, here is the podtest.sh script:

#!/bin/dash

echo This is a plain shell script
echo Followed by POD documentation

: <<=cut
=pod
=head1 NAME

   podtest.sh - Example shell script with embedded POD documentation

...

No rights Reserved

=cut

To add this podtest.sh to your man pages:

 pod2man podtest.sh >/usr/local/share/man/man1/podtest.sh.1