phpDocumentor/ApiGen@author标签位置

我很想把这作为一个一般的编程问题来发表。我之所以不这么做，是因为不同的文档系统处理标记的方式不同，因此对特定语言的“对”或“错”强加了自己的规则

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

有一个标签我不知道放在哪里，@author标签。我想把它和文件级的doc块放在一起。连同@copyright、@license、@package和@link。而不是在类级文档块中。对于某些上下文：我的PHP文件只包含一个类声明

然而，我没有发现支持这一点的证据是公认的标准。事实上，很少有信息表明应该选择哪个位置。这让我相信，我可能应该在文件级doc块和类级doc块中都包含这些信息

一些例子： OpenEMR似乎更喜欢在文件级块以及类级块（）中使用@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
{

}

---

您可以使用它来记录任何元素，因此，只要它适合并有助于您的需要，就可以使用它

描述 @author标记用于记录可以记录的任何元素（全局变量、include、常量、函数、define、类、变量、方法、页面）的作者。phpDocumentor将获取尖括号之间的任何文本

（<和>）

并尝试将其解析为电子邮件地址。如果成功，将在页面中显示mailto链接 新版本1.2-@author现在由子类从父类继承，请参见内联{@inheritdoc}

例子

/**
*页面级DocBlock示例。
*显示为Gregory Beavercellog@php.net
*，其中带下划线的文本为“mailto:cellog@php.net“链接
*@作者Gregory Beaver
*/
/**
*函数数据函数
*另一个参与者编写了此函数
*@作者乔·什莫
*/
函数datafunction（）
{
...
}

编辑以澄清：大多数情况下，类本身位于文件中，因此文件和类作者是相同的。因此，在文件级块中，您可能只有一个

@author

标记。但并非总是这样：可能文件是由项目团队自动生成的占位符，由其他作者实现，或者文件中有一些额外的代码，比如一次性的

if

语句来定义一些函数（如果它不存在）。在这种情况下，文件和类可能需要不同的

@author

标记

如果你担心清晰度，或者觉得有更多的细节是有帮助的，把它放在两个地方；不会痛的。就个人而言，如果我要添加

@author

标记，我会将它们添加到每个文件和几乎每个重要的代码块中。如果一个类有可能在将来的某个时候变成接口或抽象类，那么这种方法是有意义的

例如，您可能有一个由Joe创建的类

DatabaseConnector

，它连接到MySQL数据库。随着时间的推移，您决定将其变得更加抽象，以便用户也可以使用PostgreSQL。因此，Bob将

DatabaseConnector

转换为一个抽象类，Joe的原始代码成为新类

DatabaseConnectorMySQL

的一部分。Joe仍然是DatabaseConnector.php的

@作者

，也是

DatabaseConnectorMySQL

中所有代码的作者，但Bob编写了当前

DatabaseConnector

中的所有代码。因此，无论是在适当的时候给予表扬，还是在有问题时告诉人们联系谁，你都想展示谁写了什么，谁负责某些选择（比如方法名）

---

或者，也许你觉得这太多了，增加了混乱，你宁愿在docblock的其他地方解释历史。或者您根本不关心

@author

标记，因为您需要的所有信息都存储在版本控制存储库中（例如，

git

）。这取决于你；这里没有错误的答案。

谢谢您的回答。我知道这在文件级文档块和类级都是可能的。我希望用我的例子来证明这一点。我的问题是要找出在什么情况下哪个位置是合适的。与中一样，@author标记何时应该在die文件级别上下文中，何时应该在类级别1中。非常感谢您的澄清。这确实有帮助。在任何情况下，您是否认为该文件的作者与该类的作者不同？我不认为您打算将第一个示例中自动生成文件的人保留在文件级块中？如果是的话，为什么会相关？能够看到谁对布局做出了最初的决定？但是，仅凭名称和电子邮件地址，就很难得出这样的结论。在现实世界中，很容易找到文件和类具有不同的

@author

标记（）的示例，尽管我不确定原因。我想不出一个文件和一个类最终会有不同作者的场景。有些项目允许在一个类文件中包含多个类或附加代码，这是一个原因。我认为这是一个错误的做法，但是，有些人不同意（），我可以看到的最广泛的使用作者标签，如果文件中的每个单独的代码元素都有自己的一组作者标签。除此之外，单文件级docblock将枚举在所有v中找到的所有author标记的超集

/**
 * 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
{ ... }

/**
 * 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
{...}

/**
 * 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()
{
...
}