如何在 PhpDocumentor 中显示继承方法的完整文档块? [英] How to display full docblocks for inherited methods in PhpDocumentor?

问题描述

我目前有代码，其中有一个抽象父类定义了一些具体方法，子类扩展了这个父类，并将使用具体方法.例如:

I currently have code where there is an abstract parent class that defines some concrete methods, and the children classes extend this parent class, and will use the concrete methods. For example:

<?php

abstract class abstract_class {
    /**
    *   I document foo.
    */
    public function foo() {
        echo "I am the foo function!";
    }
}

class child_class {
    /**
    *   I document bar.
    */
    public function bar() {
        echo "I am the bar function!";
    }
}

?>

在我的 child_class 文档中，我看到我的 bar() 函数有很好的文档记录，包括方法摘要和方法的详细描述...但是我继承的 foo() 函数仅声明为继承我需要点击一个链接来查看它的完整文档，甚至只是看到它可以被这个函数调用.我所看到的一个例子显示在图像这里中.(我是新用户，不能放图片...)

In my documentation for child_class, I see my bar() function well documented, both in the Method summary and verbose description of the method...but my foo() function, which was inherited, is only stated to be inherited and I need to follow a link to see its full documentation, and even just see that it is callable by this function. An example of what I see is shown in the image here. (I can't put the image here because I am a new user...)

根据 PhpDocumentors 文档 我应该能够以某种方式查看 Docblock，但我不知道该怎么做:

According to the PhpDocumentors documentation I should be able to see the Docblock somehow, but I don't know how to do so:

1.2.0 版中的新功能，DocBlock 由子类、变量和方法继承.

New in version 1.2.0, DocBlock's are inherited by child classes, variables, and methods.

在从命令行调用 phpdoc 时，我四处寻找开关或要运行的东西，但没有找到任何东西.

I looked all over for a switch or something to run when calling phpdoc from a command-line but haven't found anything.

如何以我想要的方式显示我想要的信息?

How can I display the information I want, in the way that I want?

推荐答案

如果你不重新声明子类中的方法，那么我认为各种输出转换器的结构只会向你展示一个继承方法的列表.一些转换器至少会包含文档块中方法的简短描述 (HTML:Smarty:PHP)，而其他转换器则不会 (HTML:frames:default).

If you do not redeclare the method in the child class, then I think the structure of the various output converters will only show you a list of inherited methods. Some converters will include at least the Short Description of the method from the docblock (HTML:Smarty:PHP), whereas others do not (HTML:frames:default).

不，没有可用于修改此行为的运行时配置或开关.这只是如何编写输出转换器以构建结果文档的问题.

No, there is no runtime config or switch that you can use to modify this behavior. This is simply a matter of how the output converters are written to structure the resulting document.

现在，如果您要在子类中再次重新声明该方法，无论是覆盖父类方法还是只是为父类的抽象方法实际实现一个具体方法，那么您在父类中编写的许多方面方法的文档块将在子方法的文档中可见.

Now, if you were to redeclare the method again in the child class, whether it be to override the parent method or to just actually implement a concrete method for a parent's abstract method, then many aspects that you had written in the parent method's docblock would then be visible in the child method's document.

按照您的示例，这可能最好通过具有抽象方法的抽象类来演示，并且它得到了完整的文档记录.然后，子类实现该方法，但没有自己的 docblock(因为按照惯例，它应该完全遵循抽象父类方法 docblock 中的描述).例如，此文档继承应该通过 param 和 return 标签可见.

Following your example, this may best be demonstrated by the abstract class having an abstract method, and it gets fully documented. Then, the child class implements the method, but has no docblock of its own (because by convention it should be perfectly following the description that's in the abstract parent's method docblock). This doc inheritance should be visible by the param and return tags being visibly inherited, for example.

这种继承行为在 Eclipse 等 IDE 中也是可见的.如果 phpDocumentor 没有在子类文档中显示这种继承，那就是一个错误.

This kind of inheritance behavior is also visible in IDEs like Eclipse. If phpDocumentor is failing to show this kind of inheritance in the child class docs, it is a bug.

这篇关于如何在 PhpDocumentor 中显示继承方法的完整文档块?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！