title: Parsing heredoc comments in BASH script
body: <p>I have a collection of Bash scripts and would like to be able to parse them to extract their definitions.</p>
  
  <p>If I form my descriptions within the scripts (ab)using heredocs for comment blocks as below, will this offer any benefits:</p>
  
  <pre><code>#!/bin/bash
  
  DESCRIPTION = &lt;&lt;EOD
  
  This nifty script does x, y and sometimes z
  
  EOD
  
  # rest of script...
  </code></pre>
  
  <p>over:</p>
  
  <pre><code>#!/bin/bash
  
  # Description
  # ==========
  #
  # This nifty script does x, y and sometimes z 
  
  # rest of script...
  </code></pre>
  
  <p>ie, is there an easy way for me to pull a variable out of a Bash script or will I need to write a script to parse the file for the properly formatted description block from <code># Description</code> to the next blank line?</p>
  
  <p><strong>Update</strong></p>
  
  <p>A lot of great answers for this. I chose the one which suits my use case and preference the best, but all are great examples of Bash commenting implementations.</p>