phaser/tasks/buildtsdoc-debug.js

/**
* Add comments in a TypeScript definition file
*/
'use strict';

var ts = require('typescript');
var fs = require('fs');
var _grunt = null;

var TypeScriptDocGenerator = (function () {

    function TypeScriptDocGenerator(tsDefFileName, jsdocJsonFileName) {

        _grunt.log.writeln("TS Defs: " + tsDefFileName + " json: " + jsdocJsonFileName);

        this.nbCharsAdded = 0;
        this.tsDefFileName = ts.normalizePath(tsDefFileName);
        this.tsDefFileContent = fs.readFileSync(this.tsDefFileName, 'utf-8').toString();
        this.delintNodeFunction = this.delintNode.bind(this);

        var jsonDocsFileContent = fs.readFileSync(jsdocJsonFileName, 'utf-8').toString();

        this.docs = JSON.parse(jsonDocsFileContent);

        _grunt.log.writeln("json parsed");

        var options = { target: ts.ScriptTarget.ES5, module: ts.ModuleKind.AMD };
        var host = ts.createCompilerHost(options);
        var program = ts.createProgram([this.tsDefFileName], options, host);

        this.sourceFile = program.getSourceFile(this.tsDefFileName);

    }

    TypeScriptDocGenerator.prototype.getTsDefCommentedFileContent = function () {

        this.scan();

        return this.tsDefFileContent;

    };

    TypeScriptDocGenerator.prototype.repeatSpaces = function (nb) {

        var res = "";

        for (var i = 0; i < nb; i++)
        {
            res += " ";
        }

        return res;

    };

    TypeScriptDocGenerator.prototype.insertComment = function (commentLines, position) {

        if ((commentLines != null) && (commentLines.length > 0))
        {
            var nbChars = 0;

            for (var i = 0; i < commentLines.length; i++)
            {
                nbChars += commentLines[i].trim().length;
            }

            if (nbChars > 0)
            {
                var lc = this.sourceFile.getLineAndCharacterFromPosition(position);
                var nbSpaces = lc.character - 1;
                var startLinePosition = this.sourceFile.getLineStarts()[lc.line - 1];
                var comment = "\r\n" + this.repeatSpaces(nbSpaces) + "/**\r\n";

                for (var j = 0; j < commentLines.length; j++)
                {
                    comment += this.repeatSpaces(nbSpaces) + "* " + commentLines[j].trimRight() + "\r\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;

                // _grunt.log.writeln("comment: " + comment);
            }
        }

    };

    TypeScriptDocGenerator.prototype.cleanEndLine = function (str) {

        return str.replace(new RegExp('[' + "\r\n" + ']', 'g'), "\n").replace(new RegExp('[' + "\r" + ']', 'g'), "\n");

    };

    TypeScriptDocGenerator.prototype.findClass = function (className) {

        // _grunt.log.writeln("findClass: " + className);

        if (className.indexOf("p2.") === 0)
        {
            className = className.replace("p2.", "Phaser.Physics.P2.");
        }

        var elements = this.docs.classes.filter(function (element) {
            return (element.name === className);
        });

        return elements[0];

    };

    TypeScriptDocGenerator.prototype.generateClassComments = function (className) {

        // _grunt.log.writeln("generateClassComments: " + className);

        var c = this.findClass(className);

        // _grunt.log.writeln("generateClassComments class found: " + JSON.stringify(c));

        if (c !== null && c !== undefined)
        {
            var comments = [];
            comments = comments.concat(this.cleanEndLine(c.description).split("\n"));
            // _grunt.log.writeln("generateClassComments return comments");
            return comments;
        }
        else
        {
            // _grunt.log.writeln("generateClassComments return null");
            return null;
        }

    };

    TypeScriptDocGenerator.prototype.generateMemberComments = function (className, memberName) {

        _grunt.log.writeln("generateMemberComments: " + className + " = " + memberName);

        var c = this.findClass(className);

        if (c !== null)
        {
            for (var i = 0; i < c.members.length; i++)
            {
                if (c.members[i].name === memberName)
                {
                    var m = c.members[i];
                    var comments = [];
                    comments = comments.concat(this.cleanEndLine(m.description).split("\n"));

                    if ((m.default != null) && (m.default !== ""))
                    {
                        comments.push("Default: " + m.default);
                    }

                    return comments;
                }
            }
        }
        else
        {
            return null;
        }

    };

    TypeScriptDocGenerator.prototype.generateFunctionComments = function (className, functionName) {

        _grunt.log.writeln("generateFunctionComments: " + className);

        var c = this.findClass(className);

        if (c !== null)
        {
            for (var i = 0; i < c.functions.length; i++)
            {
                if (c.functions[i].name === functionName)
                {
                    var f = c.functions[i];
                    var comments = [];
                    comments = comments.concat(this.cleanEndLine(f.description).split("\n"));

                    if (f.parameters.length > 0)
                    {
                        comments.push("");
                    }

                    for (var j = 0; j < f.parameters.length; j++)
                    {
                        var p = f.parameters[j];

                        if (p.type === "*")
                        {
                            p.name = "args";
                        }

                        var def = "";

                        if ((p.default != null) && (p.default !== ""))
                        {
                            def = " - Default: " + p.default;
                        }

                        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 : ""));
                            }
                            else
                            {
                                comments.push(this.repeatSpaces(("@param " + p.name + " ").length) + paramComments[k].trim() + ((k === paramComments.length - 1) ? def : ""));
                            }
                        }
                    }

                    if ((f.returns != null) && (f.returns.description.trim().length > 0))
                    {
                        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;
                }
            }
        }
        else
        {
            return null;
        }

    };

    TypeScriptDocGenerator.prototype.generateConstructorComments = function (className) {

        _grunt.log.writeln("generateConstructorComments: " + className);

        var c = this.findClass(className);

        if (c !== null)
        {
            // _grunt.log.writeln("Class: " + c);

            var con = c.constructor;
            var comments = [];

            comments = comments.concat(this.cleanEndLine(con.description).split("\n"));

            if (con.parameters.length > 0)
            {
                comments.push("");
            }

            for (var j = 0; j < con.parameters.length; j++)
            {
                var p = con.parameters[j];

                if (p.type === "*")
                {
                    p.name = "args";
                }

                var def = "";

                if ((p.default != null) && (p.default !== ""))
                {
                    def = " - Default: " + p.default;
                }

                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 : ""));
                    }
                    else
                    {
                        comments.push(this.repeatSpaces(("@param " + p.name + " ").length) + paramComments[k].trim() + ((k === paramComments.length - 1) ? def : ""));
                    }
                }
            }

            return comments;

        }
        else
        {
            return null;
        }

    };

    TypeScriptDocGenerator.prototype.scan = function () {

        this.delintNode(this.sourceFile);

    };

    TypeScriptDocGenerator.prototype.getClassName = function (node) {

        // _grunt.log.writeln("getClassName: " + JSON.stringify(node));
        // _grunt.log.writeln("getClassName: " + JSON.stringify(node.kind));
        // _grunt.log.writeln("getClassName: " + JSON.stringify(node.name));

        var fullName = '';

        if (node.name !== undefined && node.kind === ts.SyntaxKind.ClassDeclaration)
        {
            // _grunt.log.writeln("getClassName 1a: " + node.name.text);

            try {
                fullName = node.name.getText();
                // _grunt.log.writeln("getClassName 1b: " + fullName);
            }
            catch (e)
            {
                fullName = node.name.text;
                // _grunt.log.writeln("getClassName bail");
                // return '';
            }
        }

        var parent = node.parent;

        while (parent !== null && parent !== undefined)
        {
            // _grunt.log.writeln("getClassName 2");

            if (parent.kind === ts.SyntaxKind.ModuleDeclaration || parent.kind === ts.SyntaxKind.ClassDeclaration)
            {
                fullName = parent.name.getText() + ((fullName !== '') ? "." + fullName : fullName);
            }

            parent = parent.parent;
        }

        if (fullName === undefined || fullName === null)
        {
            fullName = '';
        }

        // _grunt.log.writeln("getClassName: " + fullName);

        return fullName;

    };

    TypeScriptDocGenerator.prototype.delintNode = function (node) {

        var c = this.getClassName(node);

        var r = true;

        try {
            r = node.getStart();
        }
        catch (e)
        {
            r = false;
        }

        switch (node.kind)
        {
            case ts.SyntaxKind.Constructor:
                // _grunt.log.writeln("insert1: " + node);

                if (c !== '' && r)
                {
                    this.insertComment(this.generateConstructorComments(c, r));
                }

                break;

            case ts.SyntaxKind.ClassDeclaration:
                // _grunt.log.writeln("insertX2: " + JSON.stringify(node));
                // _grunt.log.writeln("insertX2a: " + JSON.stringify(node.name));
                // _grunt.log.writeln("insertX2b: " + this.getClassName(node));
                // _grunt.log.writeln("insertX2c: " + r);
                // _grunt.log.writeln("insertX2d ...");

                if (c !== '' && r)
                {
                    this.insertComment(this.generateClassComments(c, r));
                }

                break;

            case ts.SyntaxKind.Property:
                // _grunt.log.writeln("insert3: " + node);

                var t = true;

                try {
                    t = node.name.getText();
                }
                catch (e)
                {
                    t = false;
                }

                if (c !== '' && r && t)
                {
                    this.insertComment(this.generateMemberComments(c, t, r));
                }

                break;

            case ts.SyntaxKind.Method:
                // _grunt.log.writeln("insert4: " + node);

                var t2 = true;

                try {
                    t2 = node.name.getText();
                }
                catch (e)
                {
                    t2 = false;
                }

                if (c !== '' && r && t2)
                {
                    this.insertComment(this.generateFunctionComments(c, t2, r));
                }

                break;
        }

        ts.forEachChild(node, this.delintNodeFunction);

    };

    return TypeScriptDocGenerator;

})();

module.exports = function (grunt) {

    _grunt = grunt;

    grunt.registerMultiTask('buildtsdoc', 'Generate a TypeScript def with comments', function () {
        var tsdg = new TypeScriptDocGenerator(this.data.tsDefFileName, this.data.jsdocJsonFileName);
        fs.writeFileSync(this.data.dest, tsdg.getTsDefCommentedFileContent(), 'utf8');
    });

};