Question

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

我应该这样做：

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

或

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

我猜测，因为类和接口在PHP中不是第一类，所以它可能是后者。但两种选择似乎都有问题。

Answer 1

我将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) {
    ...
}

Answer 2

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

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

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

如何正确记录方法参数应该是实现某个接口的类名？

2 个答案: