phpDocumentor / ApiGen @author 标签位置

Question

我很乐意将此作为一般编程问题发布。我不这样做的原因是不同的文档系统处理标签的方式不同，因此对特定语言的“正确”或“错误”施加了自己的规则。

现在有问题的语言是 PHP。到目前为止，它还没有“标准”文档系统。有 phpDocumentor，虽然作为一个项目已经过时，但它似乎已经建立了基础。像 ApiGen 这样的当前产品似乎在努力支持它的语法。

我不太清楚该放在哪里的一个标签是@author 标签。我想把它放在文件级文档块中。连同@copyright、@license、@package 和@link。而不是在类级别的文档块内。对于某些情况：我的 PHP 文件每个只包含一个类声明。

但是，我未能找到支持这一标准的证据。确实很少有信息可以找到应该首选的位置。这让我相信我可能应该在文件级别的文档块和类级别中都包含这些信息。

一些例子： OpenEMR 似乎更喜欢在文件级块和类一级 (http://www.open-emr.org/wiki/index.php/How_to_Document_Your_Code_Properly) 内使用 @author。该文档没有说明是打算同时发生还是仅在文件不包含类而是包含许多函数时发生：

/**
 * library/sql_upgrade_fx.php Upgrading and patching functions of database.
 *
 * Functions to allow safe database modifications
 * during upgrading and patches.
 *
 * Copyright (C) 2008-2012 Rod Roark <rod@sunsetsystems.com>
 *
 * LICENSE: This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 3
 * of the License, or (at your option) any later version.
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <http://opensource.org/licenses/gpl-license.php>;.
 *
 * @package OpenEMR
 * @author  Rod Roark <rod@sunsetsystems.com>
 * @author  Brady Miller <brady@sparmy.com>
 * @link    http://www.open-emr.org
 */

/**
 * inline tags demonstration
 *
 * This class generates bars using the main algorithm, which also 
 * works heavily with {@link foo()} to rule the world. If I want
 * to use the characters "{@link" in a docblock, I just use "{@}link."  If
 * I want the characters "{@*}" I use "{@}*}"
 *
 * @author ahobbit
 * @copyright middleearth.org XVII
 * @version 1.2.3
 */
class bar
{

}

然而，ApiGen 引用的两个项目（Doctrine ORM API 和 Nette API）似乎没有在文件级别的文档块中使用@author 标签，而是在类级别的文档块中使用。但是，我在浏览包含类声明的示例时看到的唯一示例。

Doctrine 正在使用 @author 和其他标签，我本来想放在文件级 doc 块中，在类级 doc 块 (http://www.doctrine-project.org/api/orm/2.4/source-class-Doctrine.ORM.AbstractQuery.html#AbstractQuery) 内：

/**
 * Base contract for ORM queries. Base class for Query and NativeQuery.
 *
 * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @link    www.doctrine-project.org
 * @since   2.0
 * @version $Revision$
 * @author  Benjamin Eberlei <kontakt@beberlei.de>
 * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
 * @author  Jonathan Wage <jonwage@gmail.com>
 * @author  Roman Borschel <roman@code-factory.org>
 * @author  Konsta Vesterinen <kvesteri@cc.hut.fi>
 */
abstract class AbstractQuery
{ ... }

Nette 虽然也只在类/接口上下文中使用@author 标签，但似乎根本没有使用@license @copyright 或@link：

/**
 * Translator adapter.
 *
 * @author     David Grudl
 */
interface ITranslator
{...}

/**
 * Component is the base class for all components.
 *
 * Components are objects implementing IComponent. They has parent component and own name.
 *
 * @author     David Grudl
 *
 * @property-read string $name
 * @property-read IContainer|NULL $parent
 */
abstract class Component extends Nette\Object implements IComponent
{...}

Answer 1

您可以使用它来记录任何元素，因此请在适合您需要且对您有帮助的地方使用它。

From the manual:

说明

@author 标签用于记录任何可记录元素的作者（全局变量、包含、常量、函数、定义、类、变量、方法、页面）。 phpDocumentor 将采用尖括号之间的任何文本

()

并尝试将其解析为电子邮件地址。如果成功，页面中会显示一个mailto链接 新 v1.2 - @author 现在由父类的子类继承，请参阅内联 {@inheritdoc}。

示例

/**
 * Page-Level DocBlock example.
 * displays as Gregory Beaver<strong>cellog@php.net</strong>
 * , where underlined text is a "mailto:cellog@php.net" link
 * @author Gregory Beaver <cellog@php.net>
 */
/**
 * function datafunction
 * another contributor authored this function
 * @author Joe Shmoe
 */
function datafunction()
{
...
}

编辑澄清：大多数时候，一个类本身就在一个文件中，所以文件和类作者是相同的。因此，您可以在文件级块中只有一个 @author 标记。但并非总是如此：也许该文件是项目团队自动生成的占位符，并且由不同的作者实现，或者文件中可能有一些额外的代码，比如一次性的 if 语句来定义一些函数，如果它尚不存在。在这种情况下，文件和类可能需要不同的@author 标签。

如果您担心清晰度或发现更多细节会有所帮助，请将其放在两个位置；它不会受伤。就个人而言，如果我要添加@author 标签，我会将它们添加到每个文件和几乎每个重要的代码块中。如果一个类有可能在未来的某个时候变成一个接口或抽象类，那么这种方法是有意义的。

例如，也许您有一个由 Joe 创建的类 DatabaseConnector，它连接到 MySQL 数据库。随着时间的推移，您决定使其更加抽象，以便用户也可以使用 PostgreSQL。因此，Bob 将DatabaseConnector 变成了一个抽象类，而Joe 的原始代码成为了一个新类DatabaseConnectorMySQL 的一部分。 Joe 仍然是 DatabaseConnector.php 和 DatabaseConnectorMySQL 中所有代码的 @author，但 Bob 编写了当前 DatabaseConnector 中的所有代码。因此，无论是在适当的时候给予信任，还是为了告诉人们有问题时可以联系谁，您都希望展示谁写了什么以及谁负责某些选择（例如方法名称）。

或者，也许您觉得这太过分了并且会增加混乱，您宁愿只是在 docblock 的其他地方解释历史。或者您可能根本不关心@author 标签，因为您需要的所有信息都存储在您的版本控制存储库中（例如，git blame）。由你决定;这里没有错误的答案。