nikic / nikic/PHP-Parser

@file docblock is associated as a comment to the following PHP statement

Open
#445 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
PHP
Stars
17.5k
Forks
1.1k
PR merge metrics
No merged PRs in 30d

Description

<?php\n
\n
/**\n
 * @file\n
 * TODO: Enter file description here.\n
 */\n
\n
/**\n
 * Implements hook_hook_info().\n
 */\n
function testmodule8b_hook_info() {\n

Gets me this:

array:1 [
  0 => PhpParser\Node\Stmt\Function_ {#219
    // SNIP
    #attributes: array:3 [
      "startLine" => 11
      "comments" => array:2 [
        0 => PhpParser\Comment\Doc {#212
          #text: """
            /**\n
             * @file\n
             * TODO: Enter file description here.\n
             */
            """
          #line: 3
          #filePos: 7
        }
        1 => PhpParser\Comment\Doc {#214
          #text: """
            /**\n
             * Implements hook_hook_info().\n
             */
            """
          #line: 8
          #filePos: 63
        }
      ]
      "endLine" => 19
    ]
  }
]

When the file has an import statement:

<?php\n
\n
/**\n
 * @file\n
 * TODO: Enter file description here.\n
 */\n
\n
use Drupal\Core\Routing\RouteMatchInterface;\n
\n
/**\n
 * Implements hook_help().\n
 */\n
function testmodule8b_help($route_name, RouteMatchInterface $route_match) {\n

the AST is:

array:2 [
  0 => PhpParser\Node\Stmt\Use_ {#170
    +type: 1
    +uses: array:1 [
      0 => PhpParser\Node\Stmt\UseUse {#228
        +type: 0
        +name: PhpParser\Node\Name {#214
          +parts: array:4 [
            0 => "Drupal"
            1 => "Core"
            2 => "Routing"
            3 => "RouteMatchInterface"
          ]
          #attributes: array:2 [
            "startLine" => 8
            "endLine" => 8
          ]
        }
        +alias: "RouteMatchInterface"
        #attributes: array:2 [
          "startLine" => 8
          "endLine" => 8
        ]
      }
    ]
    #attributes: array:3 [
      "startLine" => 8
      "comments" => array:1 [
        0 => PhpParser\Comment\Doc {#212
          #text: """
            /**\n
             * @file\n
             * TODO: Enter file description here.\n
             */
            """
          #line: 3
          #filePos: 7
        }
      ]
      "endLine" => 8
    ]
  }
  // ... etc

In both cases, the @file docblock should be treated the same in the AST.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the two parsing examples in the issue and compare the resulting AST comment attributes for the @file docblock. Trace the parser entry point and comment-association logic involved; done means the @file docblock is represented consistently whether or not the file contains an import statement.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
compilers
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.