Merge pull request phaserjs#1385 from pnstickne/wip-jsdoc-core2

jsdoc core/plugins

Author: photonstorm

tasks/jsdoc-conf.json

@@ -20,18 +20,21 @@
             "./src/system/", 
             "./src/tilemap/", 
             "./src/time/", 
-            "./src/tween/", 
-            "./src/utils/" 
+            "./src/tween/",
+            "./src/utils/"
         ],
         "exclude": [
             "./src/physics/p2/p2.js"
         ],
         "includePattern": ".+\\.js(doc)?$",
         "excludePattern": "(^|\\/|\\\\)_"
     },
-    "plugins"   : [
+    "plugins": [
+        "./tasks/jsdoc-plugins/namealias",
+        "./tasks/jsdoc-plugins/filterpixi",
         "./tasks/jsdoc-plugins/proptomember",
         "./tasks/jsdoc-plugins/sourceproxy",
+        "./tasks/jsdoc-plugins/shortlinks",
         "plugins/markdown"
     ],
     "templates": {

tasks/jsdoc-plugins/filterpixi.js

@@ -0,0 +1,42 @@
+/**
+* Mark various PIXI properties/methods as private if they are not relevant to Phaser. 
+*/
+
+var path = require('path');
+
+function docletParamsAcceptInteractionData (doclet) {
+
+    if (Array.isArray(doclet.params)) {
+        return doclet.params.some(function (p) {
+            return p.type && p.type.names.some(function (n) {
+                return n === 'PIXI.InteractionData';
+            });
+        });
+    }
+
+}
+
+var unwantedNames = {
+    'PIXI.DisplayObject#defaultCursor': 1,
+    'PIXI.DisplayObject#interactive' : 1
+};
+
+function hasUnwantedName (doclet) {
+
+    var longname = doclet.longname;
+    return unwantedNames[longname];
+
+}
+
+exports.handlers = {};
+exports.handlers.newDoclet = function (e) {
+
+    var doclet = e.doclet;
+
+    if (docletParamsAcceptInteractionData(doclet) ||
+        hasUnwantedName(doclet))
+    {
+        doclet.access = 'private';
+    }
+
+};

tasks/jsdoc-plugins/namealias.js

@@ -0,0 +1,31 @@
+/**
+* When JSdoc encounters names it disables the automatic code inspection ability;
+* this is especially problematic for cases like
+*
+* > @class MyClass
+* > @constructor
+*
+* because the properties without an explicit @memberof or fullname are not being included in
+* in the newer JSDoc output.
+*
+* This is a simple plugin, as discussed https://github.com/jsdoc3/jsdoc/issues/804#event-195287680
+* to rewrite the @class [@constructor] to @alias @class which enables JSDoc to collect better data.
+*/
+
+exports.handlers = {};
+exports.handlers.jsdocCommentFound = function (e) {
+
+    var raw = e.comment;
+
+    var m = /^(\s*[*])\s*@class\b/m.exec(raw);
+    if (m)
+    {
+        // @class X -> @alias X / @class
+        raw = raw.replace(/^(\s*[*])\s*@class[ \t]+(\S+).*?((?=[\r\n]+))/mg, "$1 @alias $2$3$1 @class");
+        // @constructor -> {removed}
+        raw = raw.replace(/^(\s*[*])\s*@constructor\b.*?(?=[\r\n]+)/mg, "$1");
+
+        e.comment = raw;
+    }
+
+};

tasks/jsdoc-plugins/shortlinks.js

@@ -0,0 +1,50 @@
+/**
+* Transform '{@link #x}' to '{@link longname#x x}' which saves lots of cumersome typing.
+*
+* This looks in @description, @classdesc and @see tags only.
+*
+* See https://github.com/jsdoc3/jsdoc/issues/483
+*/
+ 
+var path = require('path');
+ 
+function expandLinks (text, parent) {
+ 
+    return text.replace(/\{\s*@link\s+([#.])([\w$.]+)\s*\}/g, function (m, mod, name) {
+        var expanded = "{@link " + parent + mod + name + " " + name + "}";
+        return expanded;
+    });
+ 
+}
+ 
+exports.handlers = {};
+exports.handlers.newDoclet = function (e) {
+ 
+    var doclet = e.doclet;
+    var parent;
+    if (doclet.kind === 'class' || doclet.kind === 'interface')
+    {
+        parent = doclet.longname;
+    }
+    else
+    {
+        // member, method, property, etc.
+        parent = doclet.memberof;
+    }
+ 
+    ['description', 'classdesc'].forEach(function (p) {
+        if (doclet[p])
+        {
+            doclet[p] = expandLinks(doclet[p], parent);
+        }
+    });
+
+    if (doclet.see && doclet.see.length)
+    {
+        for (var i = 0; i < doclet.see.length; i++)
+        {
+            doclet.see[i] = expandLinks(doclet.see[i], parent);
+        }
+    }
+ 
+};

tasks/jsdoc-plugins/sourceproxy.js

@@ -1,6 +1,8 @@
 /**
-* For use with custom `@sourcepath`, `@sourceline`, `@nosource` properties
-* (which are used in YUIDoc-to-JSDoc to supply source documentation)
+* Moves information from custom `@sourcepath`, `@sourceline`, `@nosource` doclets
+* into the doclet meta-information.
+*
+* This is useful to maintain source file/lineno links with the YUIDoc-to-JSDoc output.
 */
 
 var path = require('path');
@@ -31,8 +33,3 @@ exports.defineTags = function(dictionary) {
     });
 
 };
-
-exports.handlers = {};
-exports.handlers.newDoclet = function (e) {
-
-};