3.0 - Confusing commentsBlocks references

[miljan-aleksic]

Hi, first of all thank you for your work :)

I found it confusing and difficult to associate comments with their methods in the current 3.0-prerelease 8 version. Taking as example:

<?php

namespace Foospace\Foo;

/**
 * Class description
 */
class FooClass
{
    /**
     * Description
     */
    public static function bar()
    {
        return $array;
    }

    /**
     * Description
     */
    public static function baz()
    {
        return $array;
    }
  
    /**
     * Description
     */
    public static function woo()
    {
        return $array;
    }
}

the AST explorer will render something like this:

// class body
[
    {
        "kind": "method",
        "leadingComments": [...],
        "body": {
            "trailingComments": [...],
        },
        ...
    },
    {
        "kind": "method",
        "body": {
            "trailingComments": [...],
        },
        ...
    },
    {
        "kind": "method",
        "body": {
            "trailingComments": [...],
        },
        ...
    }
]

The confusing part is that the trailing comments are part of the method body, which is not accurate.

And I would expect each method to have it leadingComments as the first one in order to access them easier.

[alexander-akait]

Looks like a bug, thanks for issue

[ichiriac]

Hi @miljan-aleksic,

Sorry for the late reply, this bug was corrected after the last release, but not yet released. With actual version master here the output :

/**
 * Class description
 */
class FooClass
{
    /**
     * Description
     */
    public static function bar()
    {
        return $array;
    }

    /**
     * Description
     */
    public static function baz()
    {
        return $array;
    }
  
    /**
     * Description
     */
    public static function woo()
    {
        return $array;
    }
    // true trailing comment
}

Program {
  "children": Array [
    Class {
      "body": Array [
        Method {
          "arguments": Array [],
          "body": Block {
            "children": Array [
              Return {
                "expr": Variable {
                  "byref": false,
                  "curly": false,
                  "kind": "variable",
                  "name": "array",
                },
                "kind": "return",
              },
            ],
            "kind": "block",
          },
          "byref": false,
          "isAbstract": false,
          "isFinal": false,
          "isStatic": true,
          "kind": "method",
          "leadingComments": Array [
            CommentBlock {
              "kind": "commentblock",
              "offset": 51,
              "value": "/**
     * Description
     */",
            },
          ],
          "name": Identifier {
            "kind": "identifier",
            "name": "bar",
          },
          "nullable": false,
          "type": null,
          "visibility": "public",
        },
        Method {
          "arguments": Array [],
          "body": Block {
            "children": Array [
              Return {
                "expr": Variable {
                  "byref": false,
                  "curly": false,
                  "kind": "variable",
                  "name": "array",
                },
                "kind": "return",
              },
            ],
            "kind": "block",
          },
          "byref": false,
          "isAbstract": false,
          "isFinal": false,
          "isStatic": true,
          "kind": "method",
          "leadingComments": Array [
            CommentBlock {
              "kind": "commentblock",
              "offset": 155,
              "value": "/**
     * Description
     */",
            },
          ],
          "name": Identifier {
            "kind": "identifier",
            "name": "baz",
          },
          "nullable": false,
          "type": null,
          "visibility": "public",
        },
        Method {
          "arguments": Array [],
          "body": Block {
            "children": Array [
              Return {
                "expr": Variable {
                  "byref": false,
                  "curly": false,
                  "kind": "variable",
                  "name": "array",
                },
                "kind": "return",
              },
            ],
            "kind": "block",
            "trailingComments": Array [
              CommentLine {
                "kind": "commentline",
                "offset": 364,
                "value": "// true trailing comment
",
              },
            ],
          },
          "byref": false,
          "isAbstract": false,
          "isFinal": false,
          "isStatic": true,
          "kind": "method",
          "leadingComments": Array [
            CommentBlock {
              "kind": "commentblock",
              "offset": 261,
              "value": "/**
     * Description
     */",
            },
          ],
          "name": Identifier {
            "kind": "identifier",
            "name": "woo",
          },
          "nullable": false,
          "type": null,
          "visibility": "public",
        },
      ],
      "extends": null,
      "implements": null,
      "isAbstract": false,
      "isAnonymous": false,
      "isFinal": false,
      "kind": "class",
      "leadingComments": Array [
        CommentBlock {
          "kind": "commentblock",
          "offset": 1,
          "value": "/**
 * Class description
 */",
        },
      ],
      "name": Identifier {
        "kind": "identifier",
        "name": "FooClass",
      },
    },
  ],

The actually ugly thing is that's the last true trailing comment, is attached on the body and not to the method, as the body is the last node on the same level... and it's much harder to fix.

I'll let you know when the the alpha9 will be released on this issue.