PHP函数声明上方的奇怪注释

Question

我注意到很多脚本都有这种类型的注释:

/**
 * Retrieve list of themes with theme data in theme directory.
 *
 * The theme is broken, if it doesn't have a parent theme and is missing either
 * style.css and, or index.php. If the theme has a parent theme then it is
 * broken, if it is missing style.css; index.php is optional. The broken theme
 * list is saved in the {@link $wp_broken_themes} global, which is displayed on
 * the theme list in the administration panels.
 *
 * @since 1.5.0
 * @global array $wp_broken_themes Stores the broken themes.
 * @global array $wp_themes Stores the working themes.
 *
 * @return array Theme list with theme data.
 */
function get_themes() {
    global $wp_themes, $wp_broken_themes;

    ...

    return $wp_themes;
} 

这似乎是某种函数的文档，但是前面带有 @ 的词是什么意思呢？

比如 @since、@global、@return、@access、@param 等等...

我知道它们的含义，但为什么要在它们前面加上 @ 呢？它们需要与某种文档应用程序进行标识吗？

- Alex

---

哇，我以前从未真正查看过 WP 源代码，global $wp_broken_themes 听起来好像有一些可怕的代码正在运行！ - Wesley Murch

它们并不是“奇怪的”。@Wesley：WP代码很可怕；嗯，它是PHP，所以想想就知道了。 - Lightness Races in Orbit

@Tomalak 关于 PHP 的厌恶：问题不在于汽车，而在于司机 :) - Wesley Murch

@Wesley：你在福特蒙迪欧上看到的糟糕驾驶员比你在一辆军用吉普车上看到的还要多：这是事实。 :) - Lightness Races in Orbit

@Tomalak：无论哪个都会在傻瓜手中崩溃，但你说得对。 - Wesley Murch

Answer 1

这是JavaDoc标准。很可能作者选择它是因为大多数IDE自动将其格式化得漂亮。

http://en.wikipedia.org/wiki/Javadoc

- pkluz

---

嘿，谢谢！你知道有没有免费的集成开发环境可以做到这一点吗？我正在使用“we builder 2010”，但它们显示为注释。 - Alex

NetBeans是一个绝妙的免费IDE，通过模块支持Java（当然还有C / ++，Python，PHP等等）！ - pkluz

我也推荐使用NetBeans，上周刚试用了一下，感觉非常不错。我一直是Notepad++的忠实用户，但现在正在尝试戒掉这个习惯，转而使用更强大的工具。 - Wesley Murch

不，它不是Javadoc，而是phpDocumentator。相似但并不相同。NetBeans可以很好地处理那种文档风格。 - Tadeck

我说的是JavaDoc标准。所有看起来类似的都是某种派生形式，phpDoc也是如此。 - pkluz

我并没有说它不是Javadoc的衍生版本（适应），我只是说它不是Javadoc。Php Documentator旨在将类似于Javadoc的注释引入PHP中。但它并不相同-它是衍生版本，更新版本，有限制，并专注于不同的语言。 - Tadeck

Answer 2

他们需要使用某种文档应用程序进行识别吗？

像phpDocumentor这样的自动文档工具非常有用，通常是记录代码的好方法。正如wasabi所指出的那样，IDE也可以捕捉到它们，并为您提供一些有用的功能，例如函数参数类型建议。

即使您没有记录代码，这也是一个好习惯-只要不要感到有必要像某些人那样过度记录（记录每一个可能的事情）。

- Wesley Murch

Answer 3

这是PHPDoc，它是深受喜爱的Javadoc格式的一种改编。

这些文档格式由于其强制一致性而更易阅读，并且对于像phpdoc这样的IDE和自动文档生成器非常有用。

- Ronny

Answer 4

看起来像是 phpDocumentor，它更或多或少地类似于 PHP 的 JavaDoc。

- mu is too short

Answer 5

这绝对是PHP Documentator。 "@something" 部分用于向文档添加信息。有关详细信息，请参见PHP Documentator的文档 - 它甚至有一个从注释生成文档文件的工具(这里)，格式为 PHP Documentator。希望这能帮到你。

- Tadeck