如何在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?

推荐答案

如果您不重新声明子类中的方法，那么我认为各种输出转换器的结构只会向您显示继承的方法的列表。某些转换器至少包括docblock中的方法的简短说明（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.

现在，如果要在子类中重新声明该方法，是否可以是重写父方法或只为父方法抽象实现一个具体方法，那么您在父方法的docblock中编写的许多方面将在子方法的文档中可见。

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中的描述）。例如，这种doc继承应该可以通过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屋！