0

我正在使用 PHPDoc。我有一个接受字符串参数的方法。该字符串应该是实现某个接口的类的名称，例如IMyInterface.

我应该这样做：

/**
 * @param string $class_name
 */
public function myMethod($class_name) {}

或者

/**
 * @param IMyInterface $class_name
 */
public function myMethod($class_name) {}

我猜由于类和接口不是 PHP 中的第一类，它可能是后者。但这两种选择似乎都有问题。

4

2 回答 2

2

我在不久前做的一个项目中使用了 ApiGen，我发现最好使用类名，因为它在文档中创建了指向这些特定类页面的链接。我没有使用过 PHPDoc，但也许它具有类似的功能并使您的文档更易于访问。

/**
* Constructor function.
*
* Creates a new user object with data provided.
*
* @return void
* @param mixed An array or object of user information to be read in.
* @param Permissions An instance of a Permissions object to associate with the user.
*/
public function __construct($data,$perms) {
    ...
}
于 2013-09-24T02:41:54.160 回答
0

在您的用例中，“字符串”是正确的，因为您确切地告诉读者要传入哪种数据类型。如果用户实际上尝试传递 IMyInterface 实现者的具体类实例，那么您的代码无疑会窒息。

如果您的方法仅用于接受代表可用接口列表的特定字符串列表，那么我建议在方法的长描述中直接说明这一点，而不是在一个参数的描述中。我还将利用 @see 标记来提供指向此方法所接受的所有接口的文档的链接。这样，您的@param 标签真正告诉读者“老兄，我必须有一个字符串”，您的方法描述解释了该方法将如何获取该字符串并将其与定义的接口相关联，@see 标签将帮助读者跳转直接连接到任何/所有接口本身。

关于 IDE 自动补全，一些 IDE 可以在您的方法代码中解释“/** @var IMyInterface $localMethodVar */”，然后会在 $localMethodVar 上提供自动补全，就好像它是 IMyInterface 的已定义实例一样。

于 2013-09-24T13:53:04.217 回答