PHP文档器。我可以从它的 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”描述的类文档块中的文本可能会正确显示指向 getProperty() 的链接，但这只是因为 getProperty() 是一个真正的方法，因此它有自己的文档。如果 getProperty() 是一个用“@method getProperty()”表示的魔法方法，那么“{@link getProperty()}”就没有任何地方可以指向了。

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