Shell Script Documentation

In Python, you can have built-in documentation within your Python script using three double-quotes to encapsulate the help doc.

$ python
Python 2.5.1 (r251:54863, May 18 2007, 16:56:43)
[GCC 3.4.4 (cygming special, gdc 0.12, using dmd 0.125)] on cygwin
Type "help", "copyright", "credits" or "license" for more information.
>>> def mysquare(n):
...     """
...     This function returns the square value of
...     input n
...     """
...     return n*n
...
>>> mysquare(4)
16
>>> help(mysquare)
Help on function mysquare in module __main__:

mysquare(n)
    This function returns the square value of
    input n

In Perl, you can include the Perl module documentation after __END__ keyword. The documentation syntax is in Perl pod format. You may want to see how the documentation looks like by viewing some of the modules in the perl library. Example:

$ cd /usr/lib/perl5/5.10/

$ grep -B 2 -A 10 __END__ CGI.pm
1;

__END__

=head1 NAME

CGI - Simple Common Gateway Interface Class

=head1 SYNOPSIS

  # CGI script that creates a fill-out form
  # and echoes back its values.

$ perldoc CGI.pm
CGI(3)                User Contributed Perl Documentation               CGI(3)

NAME
       CGI - Simple Common Gateway Interface Class

SYNOPSIS
         # CGI script that creates a fill-out form
         # and echoes back its values.

         use CGI qw/:standard/;
         print header,
               start_html('A Simple Example'),
               h1('A Simple Example'),
               start_form,
               "What's your name? ",textfield('name'),p,
               "What's the combination?", p,
               checkbox_group(-name=>'words',
                              -values=>['eenie','meenie','minie','moe'],
                              -defaults=>['eenie','minie']), p,
               "What's your favorite color? ",
               popup_menu(-name=>'color',
                          -values=>['red','green','blue','chartreuse']),p,
               submit,
               end_form,

However, it seems that there isn't anything equivalent for shell script. Most people will include comments at the beginning of the file just after the Shebang. Suppose the shell script documentation is located at the beginning of the file and a blank line terminates the documentation. Base on this principle, we can simply write a wrapper function (shdoc) to extract the shell script documentation.

$ shdoc()
{ 
        echo "Documentation - \"$1\""
        echo ""
        awk '
                NR>1 && /^#/ {
                        print substr($0,2,length($0))
                }
                /^$/ {
                        exit
                }' $1
}


$ cat a.sh
#! /bin/sh
#
# This program output the current date
# from the system
#
# Exit status:
# 0 - Weekday
# 1 - Sunday
# 2 - Saturday


echo "Today date is `date '+%Y-%m-%d'`"
d=`date '+%w'`
if [ $d -eq 0 ]; then
        exit 1
elif [ $d -eq 6 ]; then
        exit 2
else
        exit 0
fi

$ shdoc a.sh
Documentation - "a.sh"


 This program output the current date
 from the system

 Exit status:
 0 - Weekday
 1 - Sunday
 2 - Saturday

Now we can auto generate documentation for all my scripts without having to worry about whether the MS Words doc in-sync with the script.