我很乐意将此作为一般编程问题发布。我不这样做的原因是不同的文档系统处理标签的方式不同，因此对特定语言的“正确”或“错误”施加了自己的规则。
现在有问题的语言是 PHP。到目前为止，它还没有“标准”文档系统。有 phpDocumentor，虽然作为一个项目已经过时，但它似乎已经建立了基础。像 ApiGen 这样的当前产品似乎在努力支持它的语法。
我不太清楚该放在哪里的一个标签是@author 标签。我想把它放在文件级文档块中。连同@copyright、@license、@package 和@link。而不是在类级别的文档块内。对于某些情况：我的 PHP 文件每个只包含一个类声明。
但是，我未能找到支持这一标准的证据。确实很少有信息可以找到应该首选的位置。这让我相信我可能应该在文件级文档块和类一级中包含这些信息。
一些示例：OpenEMR 似乎更喜欢在文件级别块内以及类级别 1 ( 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
{...}