PHPDocumentor。我可以从它的 getter 描述中添加到属性的链接吗？

Question

/**
* @property $Property
*/
class SomeClass {

    public function __get($name){
       return $this->{'get'.$name};
    }

    /**
     * Some description
     * @return bool
     */
    public function getProperty(){
       return true;
    }

}

所以问题是 - 如何通过查看 $Property 的文档来查看 getProperty() 的描述？或者只查看 getProperty() 文档的链接...

Answer 1

题目好像是反题。您想查看属性并查看 getter 的描述，还是查看 getter 并查看属性的描述？

我假设您两者都想要。但是，您实际上也无法获得。至多，一个人的描述可以包含到另一个人的链接，但实际上不会在自己的描述中包含另一个人的描述。

在这里，属性的描述将包含指向 getter 文档的链接。

/**
 * @property $Property is controlled by {@link getProperty()}.
 */
class SomeClass {

    public function __get($name){
       return $this->{'get'.$name};
    }

    /**
     * Gets the value of {@link $Property}.
     * @return bool
     */
    public function getProperty(){
       return true;
    }

}

这里有两个复杂的问题:关于神奇的东西在实际文档中的出现方式(以及 IDE 如何显示它们)；以及 {@link} 内联标签是否真的做了任何事情。

在 phpDocumentor 1.x 中，神奇的东西只作为类本身列出的额外信息出现。在 phpDocumentor 2.x 中，魔法属性和魔法方法看起来就像是真实的属性和方法一样。 2.x 行为是一个很大的改进。对于 IDE，我只能代表 Eclipse PDT，我发现它符合 1.x 的行为。

在 phpDocumentor 1.x 中，内联 {@link} 标签起作用，并且通常成为它指向的元素(属性、方法)的文档的超链接。然而，由于 1.x 实际上并没有为 @property 和 @method 标识的神奇事物创建专用文档，因此“{@link $Property}”实际上不能指向任何东西。显示“@property $Property”描述的类文档 block 中的文本可能正确显示指向 getProperty() 的链接，但这只是因为 getProperty() 是 true 方法，因此它有自己的文档。如果 getProperty() 是一个由“@method getProperty()”表示的神奇方法，那么“{@link getProperty()}”将无处可指向。

在 phpDocumentor 2.x 中，内联 {@link} 标签没有实现，因此它最终只是一个可见的文本，就好像它没有标签目的一样。一旦 2.x 实现了这个内联标记，那么我上面的解决方案应该能够解决您的两个潜在问题。