我应该如何 PHPDoc 回调？

Posted 2023-02-22

技术标签:

【中文标题】我应该如何 PHPDoc 回调？【英文标题】：How should I PHPDoc a callback? 【发布时间】：2011-06-22 13:57:07 【问题描述】：

我有一种方法可以从数据库中提取修改后的预排序树横向树，并使用回调函数对其进行过滤。例如：

/**
 * Recursive function for building the Cas_Template_TreeNode.
 *
 * @static
 * @param array $rows
 * @param callback $filter A function to filter the tree by (return a value convertible to false to remove the item from the tree)
 * @return array
 */
private static function MakeTreeGivenDbRows($rows, $filter = null)

    if ($filter === null)
    
        $filter = function($unused)
        
            return true;
        ;
    
    $result = array();
    $childrenCount = 0;
    for ($idx = 0; $idx < count($rows); $idx += $childrenCount + 1)
    
        $current = $rows[$idx];
        $childrenCount = self::ChildrenCountFromRow($current);
        if (!$filter($current))
        
            continue;
        
        $childrenStartAt = $idx + 1;
        $childRows = array_slice($rows, $childrenStartAt, $childrenCount);
        $children = self::MakeTreeGivenDbRows($childRows, $filter);
        $result[] = new Cas_Template_TreeNode(self::MakeNodeGivenDbRow($current), $children);
    
    if (empty($result))
    
        return null;
    
    return $result;

我不确定变量 $filter 的 phpDoc 应该是什么——这是一个回调，这是我所指出的，但我不确定这是否正确。

此外，任何其他关于此代码质量（或缺乏质量）的 cmets 将不胜感激:)

【问题讨论】：

【参考方案1】：

正确的类型提示是callable，它已经在例如 PhpStorm 中提供了很长时间，并且是 PSR-5 的一部分，目前正在规范中。

（我很惊讶没有其他人提到 callable，它并不是什么新鲜事，并且多年来一直在各处使用 - 据我所知，callback 不是也从来不是一个定义的 PHP pseudo-type）

请注意，callable 不仅包括闭包，还包括“老派” PHP 回调，例如array($object, 'methodName') 或 array('ClassName', 'methodName') 甚至 'function_name'- 为了最大化 API 的有用性，您应该涵盖所有这些用例，这很容易，因为 call_user_func 和 call_user_func_array 都支持所有四种可调用对象：函数名作为字符串、对象/方法名、类/方法名和闭包。

【讨论】：

写完所有这些答案后，callback 是正确答案。引用您链接到的 PHP 伪类型文章：“在 PHP 5.4 引入可调用类型提示之前，本文档中使用了回调伪类型。它的含义完全相同。”所有其他答案和问题都早于 PHP 5.4，所以当时它们是正确的。【参考方案2】：

"callback" 确实在 phpDocumentor 中作为有效数据类型工作......我刚刚验证了它......至少使用 PHP 5.2.4。 “有效数据类型”取决于您运行 phpDocumentor 所使用的 PHP 版本，这是可行的。

【讨论】：

这个答案在编写时是正确的。但是，从 PHP 5.4 开始，它不再是正确答案。【参考方案3】：

phpDoc 并没有真正指定接受的变量类型是什么，只是它们应该是有效 php 变量类型的名称。在这种情况下，“回调”是正确的。这就是 PHP 中伪类型的名称。

【讨论】：

【参考方案4】：

@param 标签的文档似乎没有在 eons 中更新，因此它没有说明任何关于使用 create_function() 进行的闭包甚至回调的内容。

如果 phpDocumentor 拒绝将 callback 识别为数据类型，您将不得不使用 mixed。

【讨论】：

我不确定它是否将callback 识别为数据类型。 @Billy ONeal：我猜你必须通过 phpDocumentor 运行 PHP 文件并找出答案。或者，如果您只是非正式地执行此操作而无需生成文档页面，只需调用它callback 也不会受到伤害。