title: documenting shell scripts' parameters
body: <p>Is there a convention for documenting shell scripts' parameters?</p>
  
  <p>For example:</p>
  
  <pre><code>#!/usr/bin/env bash
  
  # &lt;description&gt;
  #
  # Usage:
  #  $ ./myScript param1 [param2]
  # * param1: &lt;description&gt;
  # * param2: &lt;description&gt;
  </code></pre>
  
  <p>A few things I don't like about this particular template:</p>
  
  <ul>
  <li>the script's file name (<code>myScript</code>) appears within the file itself</li>
  <li>parameter description seems weird</li>
  <li>the leading space before <code>$</code> 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)</li>
  </ul>
  
  <p>Are there any guidelines on this?</p>