v. 2.0 - Comment attachment

B.C. In v. 2.0 the onComment option will be removed and replaced with attachComment.

Acorn offers the onComment option so you can use a 3rd party library to attach comments into the AST, and both Babel and Esprima have their own algorithm to do it. And for everyone this algorithm is a PITA. Comments are misplaced, can’t find correct AST node to hook them on, or they doesn’t get attached even if they should.

Upcoming v. 2.0 will change this.

A normal trailing comment will be inserted into the AST like this:

   foo /* bar */

// Output

{
    "type": "Program",
    "sourceType": "script",
    "body": [{
        "type": "Identifier",
        "name": "foo"
    }, {
        "type": "MultiLineComment",
        "value": " bar ",
        "inner": false,
        "trailing": true,
        "leading": false
    }]
}

Other cases is real tricky to handle. Both Esprima and Babel fail to insert and parse this case comment 'foo( /* bar */)' correctly. Instead the Babel parser returns a simple ‘comments’ array at the end of the Program node. It gives a headache to figure out where it belong.

If we look closely at this case foo( /* bar */), we will see that this comment is part of the argument list of the call expression.

In v. 2.0 this AST will be returned:

{
    "type": "Program",
    "sourceType": "script",
    "body": [{
        "type": "ExpressionStatement",
        "expression": {
            "type": "CallExpression",
            "callee": {
                "type": "Identifier",
                "name": "foo"
            },
            "arguments": [{
                "type": "MultiLineComment",
                "value": " bar ",
                "inner": false,
                "trailing": false,
                "leading": false
            }],
            "optional": false
        }
    }]
}

Arrows is another odd thing when it comes to Babel and Esprima.

While parsing ( /* 123 abc */) => {} - Babel name this one a “leading comment”, and in Esprima this is a “inner comment”. In both cases this comment is part of the arrow function’s body.

If we look closely at this comment, we will notice it’s part of the param list of the arrow function head.

v. 2.0 output will be:

{
    "type": "Program",
    "sourceType": "script",
    "body": [{
        "type": "ExpressionStatement",
        "expression": {
            "type": "ArrowFunctionExpression",
            "body": {
                "type": "BlockStatement",
                "body": []
            },
            "params": [{
                "type": "MultiLineComment",
                "value": " 123 abc ",
                "inner": true,
                "trailing": false,
                "leading": false
            }],
            "async": false,
            "expression": false
        }
    }]
}

And for multiple multi line comments like this case ( /* a */ /* b */ /* c */ /* d */ /* e */ ) => {} - the result will be:

{
    "type": "Program",
    "sourceType": "script",
    "body": [{
        "type": "ExpressionStatement",
        "expression": {
            "type": "ArrowFunctionExpression",
            "body": {
                "type": "BlockStatement",
                "body": []
            },
            "params": [{
                "type": "MultiLineComment",
                "value": " a ",
                "inner": true,
                "trailing": false,
                "leading": true
            }, {
                "type": "MultiLineComment",
                "value": " b ",
                "inner": true,
                "trailing": false,
                "leading": true
            }, {
                "type": "MultiLineComment",
                "value": " c ",
                "inner": true,
                "trailing": false,
                "leading": true
            }, {
                "type": "MultiLineComment",
                "value": " d ",
                "inner": true,
                "trailing": false,
                "leading": true
            }, {
                "type": "MultiLineComment",
                "value": " e ",
                "inner": true,
                "trailing": false,
                "leading": true
            }],
            "async": false,
            "expression": false
        }
    }]
}

cc/ @GuyLewin @nchanged @aladdin-add

[fisker]

Maybe

{
      "type": "ForStatement",
      "init": null,
      "test": {
		type: 'Null',
		comments: []
	  },
      "update": null,
    }

Make all null Node to {type: 'Null'}

And maybe we can redesign arrays too.

Can be

foo(/*comment*/)

{
            "type": "CallExpression",
            "arguments": {
				type: "List",
				comments: [
					/*comment*/
				],
			},
        }
    }

// -----------
foo(arg1 /*comment1*/, /*comment2*/)

{
            "type": "CallExpression",
            "arguments": {
				type: "List",
				// Or put this list to `List.data` or something
				0: {
					type: 'Identifier',
					comments: [/*comment1*/]
				},
				length: 1,
				comments: [
					/*comment2*/
				],
			},
        }
    }

[KFlash]

Agree.

cc / @3cp