您如何内联记录您的 PHP 函数和类？ [关闭]

Posted 2023-02-21

【中文标题】您如何内联记录您的 PHP 函数和类？ [关闭]

【英文标题】：How do you document your PHP functions and classes inline? [closed]

【发布时间】：2010-11-14 01:03:11

【问题描述】：

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

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

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

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

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

【问题讨论】：

你最近的编辑是什么意思？我不明白“如何生成此内联文档”的意思。

对不起，澄清一下：我问的是如何在示例中生成代码注释（或“内联文档”）的类型。

【参考方案1】：

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

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

【参考方案2】：

PHPDoc，就像您发布的内容一样，是一种被广泛接受的 PHP 文档形式。

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

编辑：就在您的代码中生成内联文档而言，我从未遇到过可以返回并在外部为项目执行此操作的工具。它通常留在 IDE 领域中，以便在您编写代码时生成模板。

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

【讨论】：

PHPDocumentor 可能是添加 API 文档的最常见和推荐的方式。

是否可以使用 PHPDoc 生成内联文档？我以为那只是为了生成文档手册。

+1 工作得非常好并且与 netbeans 集成。

我想做出区分：PHPDoc 是 cmets 的语法（改编自 JavaDoc）en.wikipedia.org/wiki/PHPDoc。 PHPDocumentor 是一个可以读取这些cmets 并生成可用文档页面/XML 的工具。还有 Doxygen，可能还有其他。

@grantwparks - 这是一个很好的澄清，谢谢。我的链接指向 PHPDocumentor，因为我将其用作 PHPDoc 语法的参考，但我通常使用 Doxygen 进行生成。我将调整链接以转到语法参考。

【参考方案3】：

通常，您会自己编写 docblock cmets，尽管我认为某些 IDE 可以为您创建模板。

我确实做到了write a program, which can trace a running program and detect parameter types and write them back as docblock comments。虽然有点小问题，但还是可以的。

【参考方案4】：

不确定你的代码是什么，但我有几个 sn-ps（我使用 Textmate），我只是在工作时添加的）我发现这最终得到了最好的结果，因为我正在填写详细信息，而不是信任系统为我做这件事。

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

【参考方案5】：

我创建了一个使用非常简单且与 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

【讨论】：

@sinse 的拼写应该是@since :')

【参考方案6】：

选择：

Doxygen phpDocumentator Sami ApiGen CakePHP API docs phpDox

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