Annotations

The purpose

The parser MUST extract any docblock, and make them available into the AST.

An docblock is a META definition of an element, so it MUST be attached to the corresponding node, and should not be an standalone element :

<?php
/**
 * @return boolean
 */
function foo() {
  /**
   * Some extra documentation
   */
  return true;
}

In the example bellow, the docblock is not giving extra information about the function like the type of return value, but not the docblock inside the function.

Attached to AST nodes

We will analyse docblocks for the following elements :

• function
• class
• interface
• trait
• assign statements

If the docblock is before any other element, it will be ignored.

How the docBlocks are attached

To be retro-compatible and to avoid extra informations (and extra processing) if not required, the grammar parser will have an option to enable or not the parsing of these docBlocks.

var reader = require('php-parser');
reader.parser.docBlocks = true;
var ast = reader.parseEval('/** @var int */ $x = 1 + 2;');
console.log(ast);

The docBlocks property on the parser object will by default be disabled. When it's disabled, docBlocks are simply ignored.

When enabling the docBlocks parsing, they will surround the AST node with annotation informations.

['program', [
  ['doc', [
    ['var', 'int']
  ], ['assign',
    ['var', ...],
    ['op', ...]
  ]]
]]

The DOC node will contains at offset 1 an array of childs parsed from the docblock contents, and at offset 2 the surrounding AST node that should be concerned by the doc block.

Readings :

• https://wiki.php.net/rfc/annotations-in-docblock
• http://doctrine-common.readthedocs.org/en/latest/reference/annotations.html
• https://wiki.php.net/rfc/annotations