title: Is there a program which can help understand another program?
body: <p>I need to document the software I'm currently working on. The software consists of several programming languages and scripts which got me thinking. If a new developers comes along and needs to fix something, they might know Java but maybe not bash scripting. It would be nice if there was a program which would help to understand what</p>
  
  <pre><code>for f in "$@" ; do
  </code></pre>
  
  <p>means. I was thinking of something that creates a static HTML page with the code plus syntax highlighting and if you hover over something (like the "for"), it would display a pop-up with an explanation: </p>
  
  <blockquote>
    <p><code>for</code> starts a loop which iterates over all values that follow <code>in</code>. In the loop, you can access each value via the variable <code>$f</code>. The loop body is between <code>do</code> and <code>done</code></p>
  </blockquote>
  
  <p>Does something like that already exist?</p>
  
  <p>[EDIT] This is just an example. You'll get another help for <code>f</code>, <code>in</code>, <code>"$@"</code>, <code>;</code> and <code>do</code>, i.e. each and every element of the line should be explained. Unknown elements (like command names) should link to Google. So you can understand what it does even if you're missing some detail.</p>
  
  <p>[EDIT2] I'm aware that you can't write a program which understands what another program does. What I'm looking for is a simple tool which will do "extended syntax highlighting" in the sense that it will color an expression and give a <strong>short</strong> explanation what it means (plus maybe a link to some in-depth reference).</p>
  
  <p>This is meant for someone who knows how to program but maybe hasn't seen some obscure construct before. Say</p>
  
  <pre><code>echo "Error" 1&gt;&amp;2
  </code></pre>
  
  <p>Every bash programmer knows what this means but a Java developer might be puzzled by the <code>1&gt;&amp;2</code> despite the fact that they can guess that <code>echo</code> == <code>System.out.println</code>. A simple "Redirects stdout to stderr" will clear things up and give that instant "AHA!" which allows them to stay in their current train of thought.</p>