我正在写一个小自制ORM(学术兴趣).我正在努力坚持TDD概念作为培训练习,作为练习的一部分,我正在编写API的文档,因为我开发了类.

举个例子 – 我正在研究经典的“getCollection”类型映射器类.我希望它能够为特定用户检索资产X的集合(比如说博客文章),以及基于任意数值的数组的集合.所以 – 你可能有一个类似于其中任何一个的方法

$User = $UserMapper->load(1);
$ArticleCollection = $ArticleMapper->getCollection(range(10,20));
$ArticleCollection = $ArticleMapper->getCollection($User);
$ArticleCollection = $ArticleMapper->getCollection($User->getId());

因此,在编写getCollection方法的文档时 – 我想在Docblock中声明@param变量.为每个参数类型设置一个唯一的方法是否更好,或者是否可以根据参数类型委托给正确的内部方法/类？

解决方法:

有一个委托给正确的内部方法的方法是可以接受的.您可以这样记录：

@param Array|User|Integer $argName optional explanation

但话又说回来,没有人阻碍你各自采用一种方法

public function getCollectionByRange(array $range)
public function getCollectionByUser(User $user)
public function getCollectionByUserId($id)

此外,您可以使用magic __call method假装存在上述方法,然后捕获对它们的方法调用并委托给您的内部方法(ZF does that f.i. for finding dependant database rows).您可以使用Class DocBlock中的@method注释来记录这些方法.但请记住,魔术方法总是比直接调用和/或调用适当的方法慢.

使用您认为对您的应用程序和用例最有意义的内容.