title: How to easily create Github friendly markdown for documented JavaScript functions?
body: <p>I want to be able to take JSDoc comments like this <em>anywhere</em> in JavaScript source (even nested down several layers of functions, in a module or even anonymous functions):</p>
  <pre><code>/**
   *  Used to do some important thing that needs doing that works like xyz.
   *  @param {String} whatever - some string that has some purpose
   *  @param {Function} callback - a function that needs to be run
   *  @returns {Boolean} whether or not something happened
   */
   function something(whatever, callback) {
       ...
  </code></pre>
  <p>and have some easy way to produce nice markdown:</p>
  <pre><code>##`root.something(whatever,callback)`
  Used to do some important thing that needs doing that works like xyz.
  
  *Parameters*
    `whatever {String}` some string that has some purpose
    `callback {Function}` a function that needs to be run
  
  *Returns*
     `{Boolean}` whether or not something happened
  </code></pre>
  <p>Where &quot;root&quot; is the namespace at which that function is reachable.  Or if it's an anonymous function or a private function (that for some reason should be in public doco, does that even make sense??), use some other convention to denote that.  Maybe</p>
  <pre><code>##_private_function_ `something(whatever,callback)`
  
    and
  
  ##_anonymous_function_`(whatever,callback)`
  </code></pre>
  <p>It doesn't have to be exactly that format, just something that looks good on Github and makes sense.  The ideal tool would be smart enough to be able to take code like <a href="https://github.com/janl/mustache.js/blob/master/mustache.js" rel="noreferrer">Mustache.js</a> and produce good output.  And extra good would be if it can handle lots of source files and produce one document as output, or a linked set of documents depending on configuration.</p>
  <p>And it would be best if this was done in a way that can be fully and easily included in a git repo so that people don't need to set up a highly specific toolchain to update the doco.  Or require a minimal toolchain at least.</p>
  <p>Oh, and a pony.</p>
  <hr />
  <h1>Existing options</h1>
  <h2><a href="http://usejsdoc.org/" rel="noreferrer">JSDoc</a>, plus some kind of HTML -&gt; markdown conversion</h2>
  <p>JSDoc is pretty good.  But I can't seem to make it work well with modules.  Or rather, it's a bigger hassle than it ought to be IMHO.  I shouldn't need to add an extra tag to name the function.  I've tried the @export and @name and still have trouble getting it to show up in the final doc the way I'd want.  If someone can point to a JSDoc commented source that has modules in it and is done well, that might help.  <strong>Update:</strong> JSDoc v3 actually seems much better with modules than v2 so this might be a better fit.</p>
  <p>Even if I could get JSDoc output like I want, I'd need to convert from HTML to markdown.  I can't seem to find a good tool for that, does one exist?</p>
  <h2><a href="https://github.com/jdalton/docdown" rel="noreferrer">Docdown</a></h2>
  <p>I played a bit with Docdown but the fact it's PHP is kind of a nonstarter for me...</p>
  <h2><a href="http://yui.github.com/yuidoc/" rel="noreferrer">YUIDoc</a>, plus conversion</h2>
  <p>I actually haven't played with YUIDoc but it looks ok.  Still, I would need a converter.  Does it deal with modules easily and avoid having to supply the function name and export name explicitly?</p>
  <h2><a href="https://github.com/visionmedia/dox" rel="noreferrer">Dox</a>, plus markdown templates</h2>
  <p>Dox produces JSON as it's output, so then you'd need to marry that to some good markdown templates, and plus include a template engine to generate the documents.  Has anyone put together a set of such templates in a useful fashion?</p>
  <h2><a href="http://jgrouse.com/" rel="noreferrer">jGrouse</a>, plus conversion</h2>
  <p>Runs with ANT.  Next...</p>
  <h2>ScriptDoc...</h2>
  <p>Does this even exist anymore?  Seems to be part of Aptana studio so that would be a nonstarter... Aptana doesn't seem to any info on it.  But ScriptDoc.org has some interesting information on crack, if that's helpful...</p>
  <h2><a href="http://pdoc.org/" rel="noreferrer">Pdoc</a></h2>
  <p>Pdoc is Ruby based but that toolchain is not uncommon so that's not a huge problem.  You can provide your own templates so maybe there are already some good markdown ones.  I haven't played with it... is it worthwhile?  Are there good markdown templates out there?</p>
  <h2>Something else?</h2>
  <p>What else is out there?</p>
  <h2>Make your own!</h2>
  <p>After messing around with JSDoc for a few hours trying to make it work how I wanted, I gave up and <a href="https://github.com/joelarson4/CharFunk/blob/master/src/java/GenDoco.java" rel="noreferrer">wrote my own quick and dirty solution in Java</a> for <a href="https://github.com/joelarson4/CharFunk" rel="noreferrer">CharFunk</a>, a unicode JavaScript library I've been working on.  It works well enough for what I need though it's not close to general purpose yet.</p>
  <hr />
  <h1>So.....</h1>
  <p>Is this an unmet need or is it just me?</p>