Merge pull request phaserjs#1287 from pnstickne/wip-props-to-members

Docs: PIXI Integration and "property to member" decorator for JSDoc

Author: photonstorm

Gruntfile.js

@@ -19,4 +19,6 @@ module.exports = function (grunt) {
 
     grunt.registerTask('dist', ['replace', 'build', 'copy']);
 
+    grunt.registerTask('docs', ['pixidoc', 'builddoc']);
+
 };

docs/build/conf.json

@@ -4,6 +4,7 @@
     },
     "source": {
         "include": [ 
+            "../pixi-jsdoc.js",
             "../../src/Phaser.js", 
             "../../src/animation/", 
             "../../src/core/", 
@@ -28,7 +29,11 @@
         "includePattern": ".+\\.js(doc)?$",
         "excludePattern": "(^|\\/|\\\\)_"
     },
-    "plugins"   : ["plugins/markdown"],
+    "plugins"   : [
+        "local-plugins/proptomember",
+        "local-plugins/sourceproxy",
+        "plugins/markdown"
+    ],
     "templates": {
         "cleverLinks"     : false,
         "monospaceLinks"  : false,
@@ -56,4 +61,4 @@
         "private": false,
         "lenient": true
     }
-}
+}

docs/build/local-plugins/proptomember.js

@@ -0,0 +1,60 @@
+/**
+* Transform @property tags to @member tags if it looks like @property was incorrectly used.
+* - That is, there is only one property and it has the same name as the member.
+* The result is less-redundancy and better type exposure in the JSDoc output.
+*
+* If the member type is not assigned then the property type is used.
+*
+* A meld of the description are used; appending the property description if appropriate.
+*
+* This approach works for most cases in Phaser because JSDoc automatically determines the name if not specified in @name, @method, @member or @field.
+*/
+
+var path = require('path');
+
+function looksLikeItMightContain (haystack, needle) {
+
+    haystack = haystack || '';
+    needle = needle || '';
+
+    haystack = haystack.replace(/[^a-z]/gi, '').toLowerCase();
+    needle = needle.replace(/[^a-z]/gi, '').toLowerCase();
+
+    return haystack.indexOf(needle) > -1;
+
+}
+
+exports.handlers = {};
+exports.handlers.newDoclet = function (e) {
+
+    var doclet = e.doclet;
+    var props = e.doclet.properties;
+
+    if (doclet.kind === 'member' &&
+        props && props.length === 1 &&
+        props[0].name === doclet.name)
+    {
+        // "Duplicate"
+        var prop = props[0];
+
+        if (!doclet.type)
+        {
+            doclet.type = prop.type;
+        }
+
+        if (!doclet.description)
+        {
+            doclet.description = prop.description;
+        }
+        else if (prop.description &&
+            !looksLikeItMightContain(doclet.description, prop.description))
+        {
+            // Tack it on..
+            doclet.description += " " + prop.description;
+        }
+
+        // And no more prop
+        e.doclet.properties = undefined;
+    }
+
+};

docs/build/local-plugins/sourceproxy.js

@@ -0,0 +1,38 @@
+/**
+* For use with custom `@sourcepath`, `@sourceline`, `@nosource` properties
+* (which are used in YUIDoc-to-JSDoc to supply source documentation)
+*/
+
+var path = require('path');
+
+exports.defineTags = function(dictionary) {
+
+    dictionary.defineTag('nosource', {
+        onTagged: function (doclet, tag) {
+            doclet.meta.nosource = true;
+            //doclet.meta.path = '';
+            //doclet.meta.filename = '';
+        }
+    });
+
+    dictionary.defineTag('sourcefile', {
+        onTagged: function (doclet, tag) {
+            var filename = tag.value;
+            doclet.meta.path = path.dirname(filename);
+            doclet.meta.filename = path.basename(filename);
+        }
+    });
+
+    dictionary.defineTag('sourceline', {
+       onTagged: function (doclet, tag) {
+           var lineno = tag.value;
+           doclet.meta.lineno = lineno;
+       }
+    });
+
+}
+
+exports.handlers = {};
+exports.handlers.newDoclet = function (e) {
+
+};

package.json

@@ -40,6 +40,7 @@
     "grunt-contrib-uglify": "^0.4.0",
     "grunt-notify": "^0.3.0",
     "grunt-text-replace": "^0.3.11",
-    "load-grunt-config": "~0.7.2"
+    "load-grunt-config": "~0.7.2",
+    "yuidocjs": "^0.3.50"
   }
-}
+}

tasks/builddoc.js

@@ -0,0 +1,30 @@
+/**
+* A quick stub-task for running generating the JSDocs.
+* This should probably be migrated to use grunt-jsdoc@beta (for jsdoc 3.x) or similar.
+*/
+'use strict';
+
+module.exports = function (grunt) {
+
+  grunt.registerTask('builddoc', 'Builds the project documentation', function () {
+
+    var done = this.async();
+
+    grunt.util.spawn({
+      cmd: 'jsdoc',
+      args: ['-c', 'conf.json', '../../README.md'],
+      opts: {
+          cwd: 'docs/build'
+      }
+    }, function (error, result, code) {
+        if (error) {
+            grunt.fail.warn("" + result);
+            done(false);
+        } else {
+            done();
+        }
+    });
+
+  });
+
+};

tasks/pixidoc.js

@@ -0,0 +1,60 @@
+/**
+* Generates the appropriate JSDoc from some (PIXI) YUIDoc.
+* This could be turned into a more general pacakge.
+*
+* Requires: yuidocjs
+*/
+'use strict';
+
+function generateYuiDoc (sourcePaths, grunt) {
+
+    var Y = require('yuidocjs');
+
+    var options = {
+        parseOnly: true,
+        quiet: true,
+        paths: sourcePaths
+    };
+
+    return (new Y.YUIDoc(options)).run();
+}
+
+module.exports = function (grunt) {
+
+  grunt.registerTask('pixidoc', 'Generates JSDoc from the PIXI YUIdocs', function () {
+
+      var sources = ['src/pixi'];
+      var output = 'docs/pixi-jsdoc.js';
+
+      var yui2jsdoc = require('./yuidoc-to-jsdoc/converter');
+      var fs = require('fs');
+      var path = require('path');
+
+      // Right now yuidocsjs requires an absolute path so it emits an
+      // absolute path in the jsdoc (or the JSDoc will error on missing files)
+      sources = sources.map(function (source) {
+        return path.resolve(source);
+      });
+
+      var data = generateYuiDoc(sources);
+
+      if (!data) {
+          grunt.fail.warn("PIXI YUIDoc not generated - nothing to do");
+          return;
+      }
+
+      // Fake in namespace (current limitation)
+      // A preamble/warning wrt the YUIDoc-to-JSDoc with proper link-outs could
+      // also be added here.
+      var header =
+        "/**\n" +
+        "* @namespace PIXI\n" +
+        "*/";
+
+      var comments = yui2jsdoc.convert(data);
+      comments.unshift(header);
+      fs.writeFileSync(output, comments.join("\n"));
+
+  });
+
+};