gr0uch/js_documentation.md

## js_documentation.md

      
    Raw
  

              js_documentation.md
            
          
    There are not enough tools in the JS ecosystem for generating docs from source code. There is dox which seems to be popular, but it is not very configurable and a bit limited in functionality in that has no lexical understanding of code. The gold standard is jsdoc but it still has its own shortcomings. It is also rigid in its expectations of input, and outputs JSON in a predefined way. I want to write a new tool that instruments code so that it has an understanding of what is being documented, and modular serializers for inputs and outputs.
Example input, JSDoc style:
App.UsersController = Framework.ArrayController.extend({
  /**
   * Get a list of inactive users.
   *
   * @public
   * @param {Number} threshold in seconds for what is considered inactive
   * @return {Array}
   */
  getInactiveUsers (threshold) { ... }
});
Many current implementations identify the comment block and then run a regular expression on the following line, without understanding the context it is in. This might be interpreted incorrectly as documentation of an anonymous function, but more importantly it misses the ArrayController.extend context. It may also not understand ES6 syntax (omitted function keyword) because their regular expressions do not account for it or their code instrumentation tool doesn't parse ES6. Moreover, they don't offer much extensibility, in that you are generally limited to JSDoc format, and implementations differ.
What I would expect as JSON output:
{
  "context": {
    "type": "method",
    "name": "getInactiveUsers",
    "scope": "Framework.ArrayController.extend"
  },
  "description": {
    "text": "Get a list of inactive users.",
    "tags": [
      {"tag": "public"},
      {"tag": "param", "name": "threshold", "type": "Number", "description": "in seconds for what is considered inactive"},
      {"tag": "return", "type": "Array"}
    ]
  }
}
The above is just one example, the idea is that the output can be user defined function, so it could output XML if you're a masochist.
Naming ideas: doccer (rhymes with soccer), docchi (rhymes with gnocchi)