Improve d.ts comments generation

-Improve the script to clean the different kinds of end of line
-Improve the alignement with @return multiline comments
-Add a jsdoc plugin to convert the class name of p2.js file, like this
the comments for the p2 classes are now included in the d.ts files.

Author: vbornand

tasks/buildtsdoc.js

@@ -18,6 +18,9 @@ var TypeScriptDocGenerator = (function () {
         this.sourceUnit = this.tree.sourceUnit();
         this.lineMap = this.tree.lineMap();
     }
+    TypeScriptDocGenerator.prototype.cleanEndLine = function (str) {
+        return str.replace(new RegExp('[' + "\r\n" + ']', 'g'), "\n").replace(new RegExp('[' + "\r" + ']', 'g'), "\n");
+    };
     TypeScriptDocGenerator.prototype.completePrefix = function (oldPrefix, appendedPrefix) {
         if (oldPrefix === "") {
             return appendedPrefix;
@@ -54,11 +57,11 @@ var TypeScriptDocGenerator = (function () {
                 var lc = this.lineMap.getLineAndCharacterFromPosition(position);
                 var nbSpaces = lc.character();
                 var startLinePosition = this.lineMap.getLineStartPosition(lc.line());
-                var comment = "\n" + this.repeatSpaces(nbSpaces) + "/**\n";
+                var comment = "\r\n" + this.repeatSpaces(nbSpaces) + "/**\r\n";
                 for (var j = 0; j < commentLines.length; j++) {
-                    comment += this.repeatSpaces(nbSpaces) + "* " + commentLines[j] + "\n";
+                    comment += this.repeatSpaces(nbSpaces) + "* " + commentLines[j].trim() + "\r\n";
                 }
-                comment += this.repeatSpaces(nbSpaces) + "*/\n";
+                comment += this.repeatSpaces(nbSpaces) + "*/\r\n";
                 this.tsDefFileContent = this.tsDefFileContent.substr(0, startLinePosition + this.nbCharsAdded) + comment + this.tsDefFileContent.substr(startLinePosition + this.nbCharsAdded);
                 this.nbCharsAdded += comment.length;
             }
@@ -80,7 +83,7 @@ var TypeScriptDocGenerator = (function () {
                 if (c.members[i].name === memberName) {
                     var m = c.members[i];
                     var comments = [];
-                    comments = comments.concat(m.description.split("\n"));
+                    comments = comments.concat(this.cleanEndLine(m.description).split("\n"));
                     if ((m.default != null) && (m.default !== "")) {
                         comments.push("Default: " + m.default);
                     }
@@ -96,7 +99,7 @@ var TypeScriptDocGenerator = (function () {
         var c = this.findClass(className);
         if (c != null) {
             var comments = [];
-            comments = comments.concat(c.description.split("\n"));
+            comments = comments.concat(this.cleanEndLine(c.description).split("\n"));
             return comments;
         }
         else {
@@ -108,7 +111,7 @@ var TypeScriptDocGenerator = (function () {
         if (c != null) {
             var con = c.constructor;
             var comments = [];
-            comments = comments.concat(con.description.split("\n"));
+            comments = comments.concat(this.cleanEndLine(con.description).split("\n"));
             if (con.parameters.length > 0) {
                 comments.push("");
             }
@@ -121,7 +124,7 @@ var TypeScriptDocGenerator = (function () {
                 if ((p.default != null) && (p.default !== "")) {
                     def = " - Default: " + p.default;
                 }
-                var paramComments = p.description.split("\n");
+                var paramComments = this.cleanEndLine(p.description).split("\n");
                 for (var k = 0; k < paramComments.length; k++) {
                     if (k === 0) {
                         comments.push("@param " + p.name + " " + paramComments[k].trim() + ((k === paramComments.length - 1) ? def : ""));
@@ -144,7 +147,7 @@ var TypeScriptDocGenerator = (function () {
                 if (c.functions[i].name === functionName) {
                     var f = c.functions[i];
                     var comments = [];
-                    comments = comments.concat(f.description.split("\n"));
+                    comments = comments.concat(this.cleanEndLine(f.description).split("\n"));
                     if (f.parameters.length > 0) {
                         comments.push("");
                     }
@@ -158,7 +161,7 @@ var TypeScriptDocGenerator = (function () {
                             def = " - Default: " + p.default;
                         }
 
-                        var paramComments = p.description.split("\n");
+                        var paramComments = this.cleanEndLine(p.description).split("\n");
                         for (var k = 0; k < paramComments.length; k++)
                         {
                             if (k === 0)
@@ -173,7 +176,16 @@ var TypeScriptDocGenerator = (function () {
 
                     }
                     if (f.returns != null) {
-                        comments.push("@return " + f.returns.description);
+                        var returnComments = this.cleanEndLine(f.returns.description).split("\n");
+                        for (var l = 0; l < returnComments.length; l++) {
+                            if (l === 0) {
+                                comments.push("@return " + returnComments[l].trim());
+                            }
+                            else
+                            {
+                                comments.push(this.repeatSpaces(("@return ").length) + returnComments[l].trim());
+                            }
+                        }
                     }
                     return comments;
                 }

tasks/jsdoc-plugins/p2completeclass.js

@@ -0,0 +1,14 @@
+/**
+* Add Phaser.Physics.P2 before the class name  in the p2.js file
+*/
+var path = require('path');
+
+exports.handlers = {};
+exports.handlers.newDoclet = function (e) {
+    var doclet = e.doclet;
+
+    if ((doclet.meta.filename === "p2.js") && (doclet.kind === 'class' || doclet.kind === 'interface'))
+    {
+        doclet.longname = "Phaser.Physics.P2." + doclet.longname;
+    }
+};

tasks/jsdocexportjson-conf.json

@@ -30,7 +30,8 @@
         "./tasks/jsdoc-plugins/namealias",
         "./tasks/jsdoc-plugins/filterpixi",
         "./tasks/jsdoc-plugins/proptomember",
-        "./tasks/jsdoc-plugins/shortlinks"
+        "./tasks/jsdoc-plugins/shortlinks",
+        "./tasks/jsdoc-plugins/p2completeclass"
     ],
     "markdown"  : {
         "parser"   : "gfm",