documenting shell scripts' parameters

Is there a convention for documenting shell scripts' parameters?

For example:

#!/usr/bin/env bash

# <description>
#
# Usage:
#  $ ./myScript param1 [param2]
# * param1: <description>
# * param2: <description>

A few things I don't like about this particular template:

• the script's file name (myScript) appears within the file itself
• parameter description seems weird
• the leading space before $ is visually useful, but can lead to confusion in languages with block comments, causing some validation tools to complain about mixed/inconsisent indentation (e.g. spaces in this block, tabs for code - provided one prefers tabs, of course)

Are there any guidelines on this?

Traditionally you document your arguments in the usage() function:

#!/bin/bash

programname=$0

function usage {
	echo "usage: $programname [-abch] [-f infile] [-o outfile]"
	echo "	-a		turn on feature a"
	echo "	-b		turn on feature b"
	echo "	-c		turn on feature c"
	echo "	-h		display help"
	echo "	-f infile	specify input file infile"
	echo "	-o outfile	specify output file outfile"
	exit 1
}

usage

I would recomment using a heredoc:

usage () {
    cat <<HELP_USAGE

    $0  [-a] -f <file>

   -a  All the instances.
   -f  File to write all the log lines
HELP_USAGE
}

instead of:

echo "$0  [-a] -f <file>"
echo
echo "-a  All the instances."
echo "-f  File to write all the log lines."

I think it is way cleaner than all these echo lines.

I usually wrap my usage in function so I can call it from a -h param etc.

#!/bin/bash
usage() {
    cat <<EOM
    Usage:
    $(basename $0) Explain options here

EOM
    exit 0
}

[ -z $1 ] && { usage; }

The Vim bash IDE that does this:

#!/bin/bash
#===============================================================================
#
#          FILE:  test.sh
#
#         USAGE:  ./test.sh
#
#   DESCRIPTION:
#
#       OPTIONS:  ---
#  REQUIREMENTS:  ---
#          BUGS:  ---
#         NOTES:  ---
#        AUTHOR:  Joe Brockmeier, [email protected]
#       COMPANY:  Dissociated Press
#       VERSION:  1.0
#       CREATED:  05/25/2007 10:31:01 PM MDT
#      REVISION:  ---
#===============================================================================

I would recommend making your script automatically print usage (if it shouldn't be run without arguments):

#!/usr/bin/env bash

if [ $# == 0 ]; then
    echo "Usage: $0 param1 [param2]"
    echo "* param1: <description>"
    echo "* param2: <description>"
fi

I would rather write:

Usage: `basename $0` [option1]|[option2] param1
  Options:
   - option1:  .....
   - option2:  .....
  Parameters:
   - param1:   ..... 

Try to look at the way help is formatted for standard UNIX utilities (ls --help, for instance)