我很想把它作为一个一般的编程问题发布。我不这样做的原因是，不同的文档系统处理标签的方式不同，因此对特定语言的"正确"或"错误"施加了自己的规则。
现在有问题的语言是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 以及其他标签，我本以为将文件级文档块放在类级文档块 （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
{...}
您可以使用它来记录任何元素，因此请在适合且有助于您需求的地方使用它。
从手册：
描述
@author 标记用于记录任何可以记录的元素（全局变量、包含、常量、函数、定义、类、变量、方法、页面）的作者。 phpDocumentor 将采用尖括号之间的任何文本
（<和>）
并尝试将其解析为电子邮件地址。如果成功，它将在页面中显示一个mailto链接NEW 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的@author.php也是DatabaseConnectorMySQL中所有代码的，但Bob编写了目前DatabaseConnector中的所有代码。因此，无论是在适当的时候给予信任，还是告诉人们如果他们有问题应该联系谁，你都希望显示谁写了什么以及谁负责某些选择（如方法名称）。
或者，也许你觉得这太多了，增加了混乱，你宁愿在文档块的其他地方解释历史。或者，也许您根本不关心@author标签，因为您需要的所有信息都存储在您的版本控制存储库中（例如，git blame ）。这取决于你;这里没有错误的答案。