您如何内联记录您的 PHP 函数和类？
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/1182781/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
How do you document your PHP functions and classes inline?
提问by James Skidmore
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? In other words, what are those forms of inline documentation that everyone agrees on, and are not significantly based on opinions; the universally accepted forms of PHP in-line documentation that everyone should know about, but as a questioner, I'm not sure of yet, but after this question is answered, I will have a good overview of, not involving any particular opinions.
内联文档的最佳和最广泛接受的形式是什么？换句话说，每个人都同意的那些形式的内联文档是什么，而不是基于意见；每个人都应该知道的普遍接受的 PHP 内联文档形式，但作为提问者，我还不确定，但是在回答这个问题之后，我将有一个很好的概述，不涉及任何特定的意见。
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."
我对生成手册不感兴趣——我想知道如何生成上面的代码注释类型或“内联文档”。
回答by zombat
PHPDoc, like what you've posted, is a widely accepted form of PHP documentation.
PHPDoc，就像您发布的内容一样，是一种被广泛接受的 PHP 文档形式。
You can use Doxygento 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 都可能具有协助此类模板生成的功能。
回答by Benoit Blanchon
回答by Olaf
I created a documentator which is very simple to use and compatible with phpdoc:
我创建了一个非常易于使用且与 phpdoc 兼容的文档器：
Example:
例子：
<?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/>";
}
?>
See in Github:
在 Github 中查看：
回答by troelskn
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.
我确实写了一个程序，它可以跟踪正在运行的程序并检测参数类型并将它们写回文档块注释。这有点马车，但它有点工作。
回答by Jason
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
一开始需要做更多的工作，但从长远来看似乎是值得的
回答by Thomas Owens
Although I haven't fully utilized it, Doxygenlooks 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 样式，然后在源文件上运行该工具以生成文档。
