是否有 PHPDoc 标准来描述通过引用传递的函数属性？答案

【问题标题】：Is there a PHPDoc standard to describe function attributes passed by reference?是否有 PHPDoc 标准来描述通过引用传递的函数属性？
【发布时间】：2020-07-16 12:40:14
【问题描述】：

我有一个使用作为引用传递的属性的函数：

public function doSomething(&$argumentPassedByReference)
{
    // ...
}

我维护我的项目的 PHPDoc，所以我这样描述我的函数：

/**
 * Do something very useful with the thing passed in parameters
 *
 * @param Type $argumentPassedByReference Thing that will be edited
 */
public function doSomething(&$argumentPassedByReference)

但我并不是很满意，因为它没有显示 $argumentPassedByReference 是通过引用传递的。 PHPDoc中是否有标准来描述这一点？

【问题讨论】：

标签： php phpdoc

【解决方案1】：

在函数定义中添加 & 符号：

 /**
 * Do something very useful with the thing passed in parameters
 *
 * @param Type &$argumentPassedByReference Thing that will be edited
 */

【讨论】：

啊，我这样做对吗？ PHPStan 声称这是错误的：PHPDoc 标记 @param 具有无效值（数组 &$config 配置（这将针对类型严格性和修剪进行修改））：意外标记“&”，偏移量 61 处的预期变量
MediaWiki 有一个custom phpcs sniff 来强制执行这种风格。就我个人而言，我觉得它很烦人而且没用——如今的 IDE 和代码生成器已经足够聪明，可以在没有任何显式标记的情况下将参数识别为参考。从技术上讲，它违反了 PSR-19，尽管 PSR-19 当然只是一个草案（而且似乎不会去任何地方）。

【解决方案2】：

Psalm 有 @param-out 用于标记输出类型 - 不完全相同，但可能有用。

【讨论】：