diff --git a/docs/build/conf.json b/docs/build/conf.json index 67c45188d..b4c4dddc6 100644 --- a/docs/build/conf.json +++ b/docs/build/conf.json @@ -28,7 +28,10 @@ "includePattern": ".+\\.js(doc)?$", "excludePattern": "(^|\\/|\\\\)_" }, - "plugins" : ["plugins/markdown"], + "plugins" : [ + "local-plugins/proptomember", + "plugins/markdown" + ], "templates": { "cleverLinks" : false, "monospaceLinks" : false, @@ -56,4 +59,4 @@ "private": false, "lenient": true } -} \ No newline at end of file +} diff --git a/docs/build/local-plugins/proptomember.js b/docs/build/local-plugins/proptomember.js new file mode 100644 index 000000000..39e941267 --- /dev/null +++ b/docs/build/local-plugins/proptomember.js @@ -0,0 +1,66 @@ +/** +* 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 || ''; + + if (!needle) { + return false; + } + + 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 (!looksLikeItMightContain(doclet.description, prop.description)) + { + // Tack it on.. + doclet.description += " " + prop.description; + } + } + + // And no more prop + e.doclet.properties = undefined; + } + +}; \ No newline at end of file