diff --git a/tasks/builddoc.js b/tasks/builddoc.js index 0bb108488..e3afabb9e 100644 --- a/tasks/builddoc.js +++ b/tasks/builddoc.js @@ -12,10 +12,7 @@ module.exports = function (grunt) { grunt.util.spawn({ cmd: 'jsdoc', - args: ['-c', 'conf.json', '../../README.md'], - opts: { - cwd: 'docs/build' - } + args: ['-c', './tasks/jsdoc-conf.json', './README.md'], }, function (error, result, code) { if (error) { grunt.fail.warn("" + result); diff --git a/tasks/jsdoc-conf.json b/tasks/jsdoc-conf.json new file mode 100644 index 000000000..825642e44 --- /dev/null +++ b/tasks/jsdoc-conf.json @@ -0,0 +1,65 @@ +{ + "tags": { + "allowUnknownTags": true + }, + "source": { + "include": [ + "./docs/pixi-jsdoc.js", + "./src/Phaser.js", + "./src/animation/", + "./src/core/", + "./src/gameobjects/", + "./src/geom/", + "./src/input/", + "./src/loader/", + "./src/math/", + "./src/net/", + "./src/particles/", + "./src/physics/", + "./src/sound/", + "./src/system/", + "./src/tilemap/", + "./src/time/", + "./src/tween/", + "./src/utils/" + ], + "exclude": [ + "./src/physics/p2/p2.js" + ], + "includePattern": ".+\\.js(doc)?$", + "excludePattern": "(^|\\/|\\\\)_" + }, + "plugins" : [ + "./tasks/jsdoc-plugins/proptomember", + "./tasks/jsdoc-plugins/sourceproxy", + "plugins/markdown" + ], + "templates": { + "cleverLinks" : false, + "monospaceLinks" : false, + "default" : { + "outputSourceFiles" : true + }, + "systemName" : "Phaser", + "footer" : "", + "copyright" : "Phaser Copyright © 2012-2014 Photon Storm Ltd.", + "navType" : "vertical", + "theme" : "cerulean", + "linenums" : true, + "collapseSymbols" : false, + "inverseNav" : true + }, + "markdown" : { + "parser" : "gfm", + "hardwrap" : true + }, + "opts": { + "encoding": "utf8", + "recurse": true, + "private": false, + "lenient": true, + "destination": "./docs", + "template": "./resources/docstrap-master/template" + + } +} diff --git a/tasks/jsdoc-plugins/proptomember.js b/tasks/jsdoc-plugins/proptomember.js new file mode 100644 index 000000000..b339366ae --- /dev/null +++ b/tasks/jsdoc-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; + } + +}; diff --git a/tasks/jsdoc-plugins/sourceproxy.js b/tasks/jsdoc-plugins/sourceproxy.js new file mode 100644 index 000000000..8b02698d6 --- /dev/null +++ b/tasks/jsdoc-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) { + +}; diff --git a/tasks/options/clean.js b/tasks/options/clean.js index f226fa4ea..8b207c28c 100644 --- a/tasks/options/clean.js +++ b/tasks/options/clean.js @@ -1,3 +1,7 @@ module.exports = { - compile_dir: ['<%= compile_dir %>'] + + docs: ['<%= docs_dir %>/*'], + dist: ['<%= compile_dir %>/*'], + out: ['out'] + }; diff --git a/tasks/options/jsdoc.js b/tasks/options/jsdoc.js new file mode 100644 index 000000000..7a83e6e5f --- /dev/null +++ b/tasks/options/jsdoc.js @@ -0,0 +1,36 @@ +module.exports = { + + dist: { + src: [ + '<%= docs_dir %>/pixi-jsdoc.js', + './src/Phaser.js', + './src/animation/', + './src/core/', + './src/gameobjects/', + './src/geom/', + './src/input/', + './src/loader/', + './src/math/', + './src/net/', + './src/particles/', + './src/physics/', + './src/sound/', + './src/system/', + './src/tilemap/', + './src/time/', + './src/tween/', + './src/utils/', + './README.md' + ], + options: { + destination: '<%= docs_dir %>', + template : 'node_modules/grunt-jsdoc/node_modules/ink-docstrap/template', + configure : './tasks/jsdoc-conf.json', + encoding: 'utf8', + recurse: true, + private: false, + lenient: true + } + } + +}; \ No newline at end of file diff --git a/tasks/options/replace.js b/tasks/options/replace.js index 964671345..92a3e8767 100644 --- a/tasks/options/replace.js +++ b/tasks/options/replace.js @@ -16,5 +16,25 @@ module.exports = { from: '!function(e){"object"==typeof exports?module.exports=e():"function"==typeof define&&define.amd?define(e):"undefined"!=typeof window?window.p2=e():"undefined"!=typeof global?global.p2=e():"undefined"!=typeof self&&(self.p2=e())}(function(){var define,module,exports;return (function e(t,n,r){function s(o,u){if(!n[o]){if(!t[o]){var a=typeof require=="function"&&require;if(!u&&a)return a(o,!0);if(i)return i(o,!0);throw new Error("Cannot find module \'"+o+"\'")}var f=n[o]={exports:{}};t[o][0].call(f.exports,function(e){var n=t[o][1][e];return s(n?n:e)},f,f.exports,e,t,n,r)}return n[o].exports}var i=typeof require=="function"&&require;for(var o=0;oLicense<\/a><\/li>\s<\/ul>)/g, + to: '' + }, + { + from: /()[\s\S]*(<\/section>\s*<\/div>\s*
<\/div>\s*
)/g, + to: '