More correct parsing for kind shorthand (@Class, @constant, etc)

* Set the `kind` property of the comment, not a property named by the kind.
* Set the `type` property as appropriate for these shorthands.
* Parse @callback as shorthand for @typedef {Function}

Author: jfirebaugh

Diff for: lib/infer/kind.js

@@ -3,11 +3,8 @@
 var shouldSkipInference = require('./should_skip_inference');
 var t = require('babel-types');
 
-var kindShorthands = ['class', 'constant', 'event', 'external', 'file',
-  'function', 'member', 'mixin', 'module', 'namespace', 'typedef'];
-
 /**
- * Infers a `kind` tag from other tags or from the context.
+ * Infers a `kind` tag from the context.
  *
  * @name inferKind
  * @param {Object} comment parsed comment
@@ -19,15 +16,6 @@ module.exports = function () {
       return comment;
     }
 
-    for (var i = 0; i < kindShorthands.length; i++) {
-      var kind = kindShorthands[i];
-      if (kind in comment) {
-        comment.kind = kind;
-        // only allow a comment to have one kind
-        return comment;
-      }
-    }
-
     function findKind(path) {
       if (!path) {
         return comment;

Diff for: lib/infer/membership.js

@@ -72,7 +72,7 @@ module.exports = function () {
   var currentModule;
 
   function inferModuleName(comment) {
-    return (comment.module && comment.module.name) ||
+    return (comment.kind === 'module' && comment.name) ||
       pathParse(comment.context.file).name;
   }
 
@@ -121,7 +121,7 @@ module.exports = function () {
 
   return shouldSkipInference(function inferMembership(comment) {
 
-    if (comment.module) {
+    if (comment.kind === 'module') {
       currentModule = comment;
     }
 

Diff for: lib/infer/name.js

@@ -4,18 +4,15 @@ var shouldSkipInference = require('./should_skip_inference'),
   pathParse = require('parse-filepath');
 
 /**
- * Infers a `name` tag from the context,
- * and adopt `@class` and other other tags as implied name tags.
+ * Infers a `name` tag from the context.
  *
  * @name inferName
  * @param {Object} comment parsed comment
  * @returns {Object} comment with name inferred
  */
 module.exports = function () {
   return shouldSkipInference(function inferName(comment) {
-
-    if (comment.event) {
-      comment.name = comment.event;
+    if (comment.name) {
       return comment;
     }
 
@@ -24,23 +21,8 @@ module.exports = function () {
       return comment;
     }
 
-    if (comment.callback) {
-      comment.name = comment.callback;
-      return comment;
-    }
-
-    if (comment.class && comment.class.name) {
-      comment.name = comment.class.name;
-      return comment;
-    }
-
-    if (comment.module) {
-      comment.name = comment.module.name || pathParse(comment.context.file).name;
-      return comment;
-    }
-
-    if (comment.typedef) {
-      comment.name = comment.typedef.name;
+    if (comment.kind === 'module') {
+      comment.name = pathParse(comment.context.file).name;
       return comment;
     }
 

Diff for: lib/parse.js

@@ -24,11 +24,22 @@ var flatteners = {
   },
   'author': flattenDescription,
   'borrows': todo,
-  'callback': flattenDescription,
-  'class': flattenTypedName,
+  'callback': function (result, tag) {
+    result.kind = 'typedef';
+
+    if (tag.description) {
+      result.name = tag.description;
+    }
+
+    result.type = {
+      type: 'NameExpression',
+      name: 'Function'
+    };
+  },
+  'class': flattenKindShorthand,
   'classdesc': flattenMarkdownDescription,
   'const': synonym('constant'),
-  'constant': flattenTypedName,
+  'constant': flattenKindShorthand,
   'constructor': synonym('class'),
   'constructs': todo,
   'copyright': flattenMarkdownDescription,
@@ -39,7 +50,13 @@ var flatteners = {
   'description': flattenMarkdownDescription,
   'emits': synonym('fires'),
   'enum': todo,
-  'event': flattenDescription,
+  'event': function (result, tag) {
+    result.kind = 'event';
+
+    if (tag.description) {
+      result.name = tag.description;
+    }
+  },
   'example': function (result, tag) {
     if (!tag.description) {
       result.errors.push({
@@ -66,12 +83,24 @@ var flatteners = {
   'exception': synonym('throws'),
   'exports': todo,
   'extends': synonym('augments'),
-  'external': flattenDescription,
-  'file': flattenDescription,
+  'external': function (result, tag) {
+    result.kind = 'external';
+
+    if (tag.description) {
+      result.name = tag.description;
+    }
+  },
+  'file': function (result, tag) {
+    result.kind = 'file';
+
+    if (tag.description) {
+      result.description = parseMarkdown(tag.description);
+    }
+  },
   'fileoverview': synonym('file'),
   'fires': todo,
   'func': synonym('function'),
-  'function': flattenName,
+  'function': flattenKindShorthand,
   'global': function (result) {
     result.scope = 'global';
   },
@@ -97,14 +126,14 @@ var flatteners = {
   'lends': flattenDescription,
   'license': flattenDescription,
   'listens': todo,
-  'member': flattenTypedName,
+  'member': flattenKindShorthand,
   'memberof': flattenDescription,
   'method': synonym('function'),
   'mixes': todo,
-  'mixin': flattenName,
-  'module': flattenTypedName,
+  'mixin': flattenKindShorthand,
+  'module': flattenKindShorthand,
   'name': flattenName,
-  'namespace': flattenTypedName,
+  'namespace': flattenKindShorthand,
   'override': flattenBoolean,
   'overview': synonym('file'),
   'param': function (result, tag) {
@@ -212,7 +241,7 @@ var flatteners = {
   },
   'tutorial': todo,
   'type': todo,
-  'typedef': flattenTypedName,
+  'typedef': flattenKindShorthand,
   'var': synonym('member'),
   'variation': function (result, tag) {
     result.variation = tag.variation;
@@ -245,13 +274,15 @@ function flattenMarkdownDescription(result, tag, key) {
   result[key] = parseMarkdown(tag.description);
 }
 
-function flattenTypedName(result, tag, key) {
-  result[key] = {
-    name: tag.name
-  };
+function flattenKindShorthand(result, tag, key) {
+  result.kind = key;
+
+  if (tag.name) {
+    result.name = tag.name;
+  }
 
   if (tag.type) {
-    result[key].type = tag.type;
+    result.type = tag.type;
   }
 }
 

Diff for: test/fixture/class.output.json

@@ -95,9 +95,8 @@
       "code": "/**\n * This is my class, a demo thing.\n * @class MyClass\n * @property {number} howMany how many things it contains\n */\nfunction MyClass() {\n  this.howMany = 2;\n}\n\n/**\n * Get the number 42\n * @param {boolean} getIt whether to get the number\n * @returns {number} forty-two\n */\nMyClass.prototype.getFoo = function (getIt) {\n  return getIt ? 42 : 0;\n};\n\n/**\n * Get undefined\n * @returns {undefined} does not return anything.\n */\nMyClass.prototype.getUndefined = function () { };\n"
     },
     "errors": [],
-    "class": {
-      "name": "MyClass"
-    },
+    "kind": "class",
+    "name": "MyClass",
     "properties": [
       {
         "name": "howMany",
@@ -160,8 +159,6 @@
         }
       }
     ],
-    "name": "MyClass",
-    "kind": "class",
     "members": {
       "instance": [
         {

Diff for: test/fixture/event.output.json

@@ -111,7 +111,8 @@
       }
     },
     "errors": [],
-    "event": "Map#mousemove",
+    "kind": "event",
+    "name": "Map#mousemove",
     "properties": [
       {
         "name": "point",
@@ -234,8 +235,6 @@
         }
       }
     ],
-    "name": "Map#mousemove",
-    "kind": "event",
     "members": {
       "instance": [],
       "static": []

Diff for: test/fixture/factory.output.json

@@ -192,11 +192,8 @@
       "code": "/**\n * an area chart generator\n * @returns {area} chart\n */\nvar area = function() {\n\n  /**\n   * @class area\n   */\n  var chart = function(selection) {\n  };\n\n  /**\n   * Sets the chart data.\n   * @function\n   */\n  chart.data = function(_) {\n  };\n\n  return chart;\n};\n"
     },
     "errors": [],
-    "class": {
-      "name": "area"
-    },
-    "name": "area",
     "kind": "class",
+    "name": "area",
     "params": [
       {
         "title": "param",
@@ -302,9 +299,8 @@
         "commentLineNumber": 0
       }
     ],
-    "function": null,
-    "name": "data",
     "kind": "function",
+    "name": "data",
     "params": [
       {
         "title": "param",

Diff for: test/fixture/inheritance.output.json

@@ -39,17 +39,14 @@
         "commentLineNumber": 0
       }
     ],
-    "class": {
-      "name": "Foo"
-    },
+    "kind": "class",
     "name": "Foo",
     "augments": [
       {
         "title": "augments",
         "name": "Bar"
       }
     ],
-    "kind": "class",
     "memberof": "module",
     "scope": "static",
     "members": {

Diff for: test/fixture/memberedclass.output.json

@@ -95,12 +95,9 @@
         "commentLineNumber": 4
       }
     ],
-    "class": {
-      "name": "MyClass"
-    },
-    "memberof": "com.Test",
-    "name": "MyClass",
     "kind": "class",
+    "name": "MyClass",
+    "memberof": "com.Test",
     "members": {
       "instance": [
         {

Diff for: test/fixture/nearby_params.output.json

@@ -142,7 +142,7 @@
       "code": "/** Attempt to establish a cookie-based session in exchange for credentials.\n *  @function\n *  @name sessions.create\n *  @param {object} credentials\n *  @param {string} credentials.name        Login username. Also accepted as `username` or `email`.\n *  @param {string} credentials.password    Login password\n *  @param {function} [callback]            Gets passed `(err, { success:Boolean })`.\n *  @returns {Promise} promise, to be resolved on success or rejected on failure\n */\nsessions.addMethod('create', 'POST / form', {\n    // normalize request body params\n    before({ body }) {\n    }\n});\n"
     },
     "errors": [],
-    "function": null,
+    "kind": "function",
     "name": "sessions.create",
     "params": [
       {

Diff for: test/fixture/params.output.json

@@ -177,9 +177,8 @@
       "code": "/**\n * This function returns the number one.\n * @param {number} b the second param\n */\nfunction addThem(a, b, c, { d, e, f }) {\n  return a + b + c + d + e + f;\n}\n\n/**\n * This method has partially inferred params\n * @param {String} $0.fishes number of kinds of fish\n */\nfunction fishesAndFoxes({ fishes, foxes }) {\n  return fishes + foxes;\n}\n\n/**\n * This method has a type in the description and a default in the code\n * @param {number} x\n */\nfunction withDefault(x = 2) {\n  return x;\n}\n\n/**\n * This is foo's documentation\n */\nclass Foo {\n  /**\n   * The method\n   * @param {number} x Param to method\n   */\n  method(x) {\n  }\n}\n\n/**\n * Represents an IPv6 address\n *\n * This tests  our support of optional parameters\n * @class Address6\n * @param {string} address - An IPv6 address string\n * @param {number} [groups=8] - How many octets to parse\n * @param {?number} third - A third argument\n * @param {Array} [foo=[1]] to properly be parsed\n * @example\n * var address = new Address6('2001::/32');\n */\nfunction Address6() {}\n\n/**\n * Create a GeoJSON data source instance given an options object\n *\n * This tests our support of nested parameters\n * @class GeoJSONSource\n * @param {Object} [options] optional options\n * @param {Object|string} options.data A GeoJSON data object or URL to it.\n * The latter is preferable in case of large GeoJSON files.\n * @param {number} [options.maxzoom=14] Maximum zoom to preserve detail at.\n * @param {number} [options.buffer] Tile buffer on each side.\n * @param {number} [options.tolerance] Simplification tolerance (higher means simpler).\n */\nfunction GeoJSONSource(options) {\n  this.options = options;\n}\n\n/**\n * This tests our support for parameters with explicit types but with default\n * values specified in code.\n *\n * @param {number} x an argument\n *\n * @returns {number} some\n */\nexport const myfunc = (x = 123) => x;\n\n/**\n * This tests our support of JSDoc param tags without type information,\n * or any type information we could infer from annotations.\n *\n * @param address - An IPv6 address string\n */\nfunction foo(address) {\n  return address;\n}\n"
     },
     "errors": [],
-    "class": {
-      "name": "Address6"
-    },
+    "kind": "class",
+    "name": "Address6",
     "params": [
       {
         "name": "address",
@@ -437,8 +436,6 @@
         "description": "var address = new Address6('2001::/32');"
       }
     ],
-    "name": "Address6",
-    "kind": "class",
     "members": {
       "instance": [],
       "static": []
@@ -1423,9 +1420,8 @@
       "code": "/**\n * This function returns the number one.\n * @param {number} b the second param\n */\nfunction addThem(a, b, c, { d, e, f }) {\n  return a + b + c + d + e + f;\n}\n\n/**\n * This method has partially inferred params\n * @param {String} $0.fishes number of kinds of fish\n */\nfunction fishesAndFoxes({ fishes, foxes }) {\n  return fishes + foxes;\n}\n\n/**\n * This method has a type in the description and a default in the code\n * @param {number} x\n */\nfunction withDefault(x = 2) {\n  return x;\n}\n\n/**\n * This is foo's documentation\n */\nclass Foo {\n  /**\n   * The method\n   * @param {number} x Param to method\n   */\n  method(x) {\n  }\n}\n\n/**\n * Represents an IPv6 address\n *\n * This tests  our support of optional parameters\n * @class Address6\n * @param {string} address - An IPv6 address string\n * @param {number} [groups=8] - How many octets to parse\n * @param {?number} third - A third argument\n * @param {Array} [foo=[1]] to properly be parsed\n * @example\n * var address = new Address6('2001::/32');\n */\nfunction Address6() {}\n\n/**\n * Create a GeoJSON data source instance given an options object\n *\n * This tests our support of nested parameters\n * @class GeoJSONSource\n * @param {Object} [options] optional options\n * @param {Object|string} options.data A GeoJSON data object or URL to it.\n * The latter is preferable in case of large GeoJSON files.\n * @param {number} [options.maxzoom=14] Maximum zoom to preserve detail at.\n * @param {number} [options.buffer] Tile buffer on each side.\n * @param {number} [options.tolerance] Simplification tolerance (higher means simpler).\n */\nfunction GeoJSONSource(options) {\n  this.options = options;\n}\n\n/**\n * This tests our support for parameters with explicit types but with default\n * values specified in code.\n *\n * @param {number} x an argument\n *\n * @returns {number} some\n */\nexport const myfunc = (x = 123) => x;\n\n/**\n * This tests our support of JSDoc param tags without type information,\n * or any type information we could infer from annotations.\n *\n * @param address - An IPv6 address string\n */\nfunction foo(address) {\n  return address;\n}\n"
     },
     "errors": [],
-    "class": {
-      "name": "GeoJSONSource"
-    },
+    "kind": "class",
+    "name": "GeoJSONSource",
     "params": [
       {
         "name": "options",
@@ -1755,8 +1751,6 @@
         ]
       }
     ],
-    "name": "GeoJSONSource",
-    "kind": "class",
     "members": {
       "instance": [],
       "static": []

Diff for: test/fixture/trailing.output.json

@@ -400,11 +400,8 @@
       }
     },
     "errors": [],
-    "class": {
-      "name": "Something"
-    },
-    "name": "Something",
     "kind": "class",
+    "name": "Something",
     "members": {
       "instance": [],
       "static": []

Diff for: test/fixture/type_application.output.json

@@ -103,9 +103,8 @@
       }
     },
     "errors": [],
-    "class": {
-      "name": "Address6"
-    },
+    "kind": "class",
+    "name": "Address6",
     "params": [
       {
         "name": "address",
@@ -177,8 +176,6 @@
         }
       }
     ],
-    "name": "Address6",
-    "kind": "class",
     "members": {
       "instance": [],
       "static": []