phpdoc - 使用现有注释自动添加 PHPDoc

Question

我想整理一个仅部分使用 PHPDoc 的大型函数包含文件。有些函数没有 PHPDoc，比如

function name($var1,$var2){ // explanation what it does
  # ...
}

还有一些 PHPDoc 存在但不完整的地方，比如缺少一些变量:

/**
  * explanation
  *
  * @param boolean $var1 foo foo foo
  *
  * @return null
  */
function name2($var1,$var2){ 
  # ...
}

或者只是

/** explanation
  */
function name3($var1,$var2){ 
  # ...
}

如何使用正确的“未知”标签添加所有缺失的变量定义和返回值？

它可以分析每个函数是否有返回值，它应该转换已经存在的注释(在每个函数后面)并在 PHPDoc 中使用它们。

我知道您将不得不手动检查结果，但是使用已经存在的数据生成一个框架真的很有帮助。

Answer 1

您可以使用 Reflection 的组合来做到这一点, token_get_all它使用 Zend 的词法扫描器将字符串解析为 PHP lanugage tokens并且很可能是正则表达式。

Reflection 的问题在于某些方法，如 ReflectionFunctionAbstract::getReturnType 仅在 PHP 7 上可用。

在 PHP 5+ 中，您可以使用 ReflectionFunctionAbstract::getParameters、ReflectionFunctionAbstract::getDocComment 等

如果没有 DocBlock，您可以使用 ReflectionFunctionAbstract::getStartLine 和 ReflectionFunctionAbstract::getEndLine 获取函数的开始和结束行，将源代码块复制到字符串并使用token_get_all 获取一组 PHP token 以单独分析。

PHP 5.6 中的反射示例:

<?php

/**
 * explanation
 *
 * @param boolean $var1 foo foo foo
 *
 * @return null
 */
 function test($var1, $var2) {

 }

 echo ReflectionFunction::export('test', true);

输出:

/**
 * explanation
 *
 * @param boolean $var1 foo foo foo
 *
 * @return null
 */
Function [ <user> function test ] {
  @@ index.php 10 - 12

  - Parameters [2] {
    Parameter #0 [ <required> $var1 ]
    Parameter #1 [ <required> $var2 ]
  }
}