Question

我知道PHP代码内联文档有许多不同的标准。这就是我对内联文档的意思，如果有更好的术语，请纠正我：

/**
* This is the description for the class below.
*
* @package    my-package
* @subpackage my-subpackage
* @author     my-name
* @version    my-version
* ...
*/
class orderActions {
...

最好和最广泛接受的内联文档形式是什么？换句话说，那些每个人都同意并且不是基于意见的内联文档形式是什么;普遍接受的PHP在线文档形式，每个人都应该知道，但作为一个提问者，我还不确定，但在回答这个问题之后，我会有一个很好的概述，不涉及任何特定的意见。

是否有任何工具可以自动生成此类文档，还是必须手动完成？

我对生成手册不感兴趣 - 我想知道如何生成上面注释的代码类型，或“内联文档”。

Answer 1

与您发布的内容一样，

PHPDoc是一种广泛接受的PHP文档形式。

您可以使用Doxygen自动生成文档。

编辑：在代码中生成内联文档方面，我从来没有遇到过一个工具，可以返回并在项目外部执行此操作。它通常留在IDE的领域，以便在编码时生成模板。

Eclipse实际上做得很好（这是我喜欢Eclipse的少数几件事之一），我相信Netbeans也是如此。任何主要IDE都可能具有协助此类模板生成的功能。

Answer 2

选择：

另请参阅Wikipedia article, "Comparison of documentation generators", section "by Language"。

Answer 3

通常情况下，你会写自己的docblock评论，虽然我想有些IDE可以为你创建一个模板。

我确实write a program, which can trace a running program and detect parameter types and write them back as docblock comments。这有点儿马车，但它有点工作。

Answer 4

我创建了一个非常简单易用且与phpdoc兼容的记录器：

示例：

<?php
    $docs = new QuickDocumenter();
    $docs->parseString("
    /**
    *   Sanitize string
    *
    *   @since      1.0
    *   @version    1.0
    */
    ");
    foreach( $docs->result() as $doc)
    {
        highlight_string( print_r( $doc , true ) );
        echo "<hr/>";
    }
?>

见Github：

https://github.com/olaferlandsen/QuickDocumenter

Answer 5

虽然我没有充分利用它，Doxygen看起来很有希望完成这项任务。

如果您熟悉Java的JavaDoc工具，那就非常相似。您使用Doxygen样式，然后在源文件上运行该工具以生成文档。

Answer 6

不确定你的代码是什么，但我有几个片段（我使用Textmate），我刚刚加入，因为我正在工作）我发现这最终得到了最好的结果，因为我填写了细节而不是信任系统为我做这件事。

一开始就有更多的工作，但从长远来看似乎是值得的

你如何在线记录你的PHP函数和类？

6 个答案: