@file docblock is associated as a comment to the following PHP statement
Open
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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