Question

我目前正在为一个安静的API构建一些phpdoc - 我开始使用@param doc语法来通过POST记录所需的参数。

然而，在生成phpdoc之后，我注意到它拒绝列出这些参数，除非它们与输入变量完全匹配到方法本身。

当涉及到phpdoc输出时，

@uses和@see看起来不太好，也没有多大意义。使用@param功能，文档的样式/外观非常完美。

有没有办法覆盖PHPDoc实施的规则，并允许它在文档中生成@param块，即使方法本身不存在param？

Answer 1

如果您想记录您的API，建议您使用API Blueprint或Open API Spec等适当的工具。

使用Swagger，您甚至可以使用annotations（这是您显然想要的）来记录API，然后从中生成文档。

不要使用PHPdoc，因为它只是混合概念。

Answer 2

您可以使用“可选”执行此操作。 IE：

@param string $variable (optional) Blah.

请参阅https://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.param.pkg.html上的其他示例。

这用于参数是可选的，无限制的参数等的用例

Answer 3

您可以考虑使用＆＃34; custom＆＃34;标记，也许@parameter，以便列出＆＃34;按原样＃34;。您不会像param标签那样获得类名的相同超链接行为，但您不会受到代码签名本身缺少参数的限制。也许在参数描述中使用内联链接标记指向参数的类类型。否则，使用，查看或链接常规标记可以位于单独的行上，作为指向作为参数类型的类的方便链接。

目前无法禁用＆＃34;实际代码签名的内部行为会覆盖param标记＆＃34;逻辑。

Answer 4

我相信您可以使用相同的方法将虚拟方法记录为变通方法，即通过该类的phpDoc标头中的@method条目。

E.g：

/**
 * ... 
 *
 * @method mixed remove(integer $pricing_group_id) Remove a group and return a JSON array with remaining groups.
 */
class YourClass {

   ...

   // see class header for phpdoc entry
    public function remove($pricing_group = null) {
        ....
    }

}

缺点是（据我所知），这种方法不提供输入方法参数和返回值的显式描述条目的方法。

Answer 5

好吧，我将用我找到的解决方案回答这个问题 - 我很欣赏所有“不要那样做”的答案，但仍然希望那些发现自己处于类似情况的人“这需要”在不改变格式的情况下立即完成，我们无法随时分配“将来会发现它有用。”

如果使用指定的param初始化方法，则可以使用@param语法进行维护，只需将其设置为null - 确保它不会破坏任何现有的调用。

/**
* Remove a group
*
* @param int $pricing_group_id Required
* @return mixed JSON array with remaining groups
*/
public function remove($pricing_group = null) {
    ....
}

您的PHPDoc输出现在将正常显示参数类型，名称和描述。

请记住，这不是好的做法 - 甚至也不是远程正确的做法。但它会起作用，直到你能说服上级给你足够的时间在更合适的平台上重建现有的文档。

PHPDoc - 在函数中没有param的情况下记录@param？

5 个答案: