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

I know there are many different standards for PHP code inline documentation. Here's what I mean by inline documentation, and please correct me if there is a better term:

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

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

What is the best and most widely-accepted form of inline documentation? Are there any tools to auto-generate such documentation, or does it have to be done by hand?

什么是最好和最广泛接受的内联文档形式？是否有任何工具可以自动生成此类文档，还是必须手动完成？

I'm not interested in generating manuals -- I want to know how to generate the type of code commenting above, or "inline documentation."

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

6 个解决方案

#1

PHPDoc, like what you've posted, is a widely accepted form of PHP documentation.

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

You can use Doxygen to auto-generate the docs.

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

Edit: In terms of generating in-line documentation in your code, I have never come across a tool that will go back and do this externally for a project. It's generally left in the realm of the IDE to generate a template while you code.

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

Eclipse actually does a decent job of this (it's one of the few things I like about Eclipse) and I believe Netbeans does as well. Any major IDE will likely have functionality to assist with this type of template generation.

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

#2

Choose from:

从中选择：

Doxygen
Doxygen的
phpDocumentator
phpDocumentator
Sami
萨米
ApiGen
ApiGen
CakePHP API docs
CakePHP API文档
phpDox
phpDox

另请参阅*文章“文档生成器的比较”，“按语言”部分。

#3

Usually, you would write the docblock comments your self, although I suppose some IDE's can create a template for you.

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

I did actually write a program, which can trace a running program and detect parameter types and write them back as docblock comments. It's a bit buggy, but it kind of works.

我确实编写了一个程序，它可以跟踪正在运行的程序并检测参数类型并将其作为docblock注释写回。这有点儿马车，但它有点工作。

#4

i created an documentator very simple to use and compatible with phpdoc:

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

Example:

例：

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

See in Github:

见Github：

https://github.com/olaferlandsen/QuickDocumenter

https://github.com/olaferlandsen/QuickDocumenter

Bye!

再见！

#5

Although I haven't fully utilized it, Doxygen looks promising for this task.

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

If you are familiar with the JavaDoc tool for Java, it's quite similar to that. You use the Doxygen style and then run the tool over your source files to produce documentation.

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

#6

Not sure what you code in but I have several snippets (I use Textmate) that I just add in as I'm working) I've found this ends up with the best results since I'm filling in the details instead of trusting a system to do it for me.

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

It's more work in the beginning but it seems to be worth it in the long run

它在开始时工作量更大，但从长远来看似乎是值得的

#1