phpDocumentor / ApiGen @author 标记位置
phpDocumentor / ApiGen @author tag location
我很乐意 post 这是一个一般的编程问题。我不这样做的原因是不同的文档系统处理标签的方式不同，因此对特定语言的 "right" 或 "wrong" 施加了自己的规则。
现在有问题的语言是 PHP。目前还没有 "standard" 文档系统。有 phpDocumentor，虽然作为一个项目已经过时，但它似乎已经建立了基础。目前的产品，如 ApiGen，似乎在努力支持其语法。
我不太清楚该放在哪里的一个标签是@author 标签。我想将它与文件级文档块放在一起。连同@copyright、@license、@package 和@link。而不是在 class 级别的文档块中。对于某些上下文：我的 PHP 文件每个只包含一个 class 声明。
但是，我没有找到支持这一标准的证据。确实很少有信息可以找到应该首选哪个位置。这让我相信我可能应该在文件级文档块和 class 一级文档块中包含此信息。
一些例子：
OpenEMR 似乎更喜欢在文件级块和 class 一级 (http://www.open-emr.org/wiki/index.php/How_to_Document_Your_Code_Properly) 内使用 @author。该文档没有具体说明是同时发生还是仅当文件不包含 class 而是包含多个函数时才发生：
/**
* 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 标签，而是专门使用 class 级别文档块。但是后来我在浏览那些包括 class 声明的地方时看到的唯一例子。
Doctrine 正在使用@author 和其他标签，我本以为放在文件级文档块中，在 class 级文档块 (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，虽然也只在 class/interface 上下文中使用 @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
{...}
您可以使用它来记录 任何 元素，因此请在适合您的需要且对您有帮助的地方使用它。
Description
The @author tag is used to document the author of any element that can be documented (global variable, include, constant, function, define, class, variable, method, page). phpDocumentor will take any text between angle brackets
(< and >)
and try to parse it as an email address. If successful, it will be displayed with a mailto link in the page
NEW v1.2 - @author is now inherited by child classes from a parent class, see inline {@inheritdoc}.
Example
/**
* 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()
{
...
}
编辑澄清： 大多数情况下，class 本身在一个文件中，因此文件和 class 作者是同一个人。因此，您可以在文件级块中只有一个 @author 标记。但并非总是如此：也许该文件是由项目团队自动生成的作为占位符，而另一位作者实现了它，或者文件中可能有一些额外的代码，比如一次性 if 语句来定义一些函数如果它不存在。在这种情况下，文件和 class 可能需要不同的 @author 标签。
如果您担心清晰度或发现提供更多详细信息有帮助，请将其放在两个地方；它不会伤害。就个人而言，如果我要添加 @author 标签，我会将它们添加到每个文件 和 几乎每个重要的代码块。如果 class 有可能在未来的某个时候变成接口或抽象 class，那么这种方法是有意义的。
例如，您可能有一个由 Joe 创建的 class DatabaseConnector，它连接到 MySQL 数据库。随着时间的推移，您决定使其更加抽象，以便用户也可以使用 PostgreSQL。所以，Bob 将 DatabaseConnector 变成了抽象的 class，而 Joe 的原始代码变成了新的 class、DatabaseConnectorMySQL 的一部分。 Joe 仍然是 DatabaseConnector.php 和 DatabaseConnectorMySQL 中所有代码的 @author，但 Bob 编写了当前 DatabaseConnector 中的所有代码。因此，无论是为了在适当的时候给予信任，还是为了告诉人们有问题时应该联系谁，您都想显示谁写了什么以及谁负责某些选择（例如方法名称）。
或者，也许您觉得这样太过分而且会增加混淆，您宁愿在文档块的其他地方解释历史。或者您可能根本不关心 @author 标签，因为您需要的所有信息都存储在您的版本控制存储库中（例如，git blame）。由你决定;这里没有错误答案。
我很乐意 post 这是一个一般的编程问题。我不这样做的原因是不同的文档系统处理标签的方式不同，因此对特定语言的 "right" 或 "wrong" 施加了自己的规则。
现在有问题的语言是 PHP。目前还没有 "standard" 文档系统。有 phpDocumentor，虽然作为一个项目已经过时，但它似乎已经建立了基础。目前的产品，如 ApiGen，似乎在努力支持其语法。
我不太清楚该放在哪里的一个标签是@author 标签。我想将它与文件级文档块放在一起。连同@copyright、@license、@package 和@link。而不是在 class 级别的文档块中。对于某些上下文：我的 PHP 文件每个只包含一个 class 声明。
但是，我没有找到支持这一标准的证据。确实很少有信息可以找到应该首选哪个位置。这让我相信我可能应该在文件级文档块和 class 一级文档块中包含此信息。
一些例子： OpenEMR 似乎更喜欢在文件级块和 class 一级 (http://www.open-emr.org/wiki/index.php/How_to_Document_Your_Code_Properly) 内使用 @author。该文档没有具体说明是同时发生还是仅当文件不包含 class 而是包含多个函数时才发生：
/**
* 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 标签，而是专门使用 class 级别文档块。但是后来我在浏览那些包括 class 声明的地方时看到的唯一例子。
Doctrine 正在使用@author 和其他标签，我本以为放在文件级文档块中，在 class 级文档块 (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，虽然也只在 class/interface 上下文中使用 @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
{...}
您可以使用它来记录 任何 元素，因此请在适合您的需要且对您有帮助的地方使用它。
Description
The @author tag is used to document the author of any element that can be documented (global variable, include, constant, function, define, class, variable, method, page). phpDocumentor will take any text between angle brackets
(< and >)
and try to parse it as an email address. If successful, it will be displayed with a mailto link in the page NEW v1.2 - @author is now inherited by child classes from a parent class, see inline {@inheritdoc}.
Example
/**
* 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()
{
...
}
编辑澄清： 大多数情况下，class 本身在一个文件中，因此文件和 class 作者是同一个人。因此，您可以在文件级块中只有一个 @author 标记。但并非总是如此：也许该文件是由项目团队自动生成的作为占位符，而另一位作者实现了它，或者文件中可能有一些额外的代码，比如一次性 if 语句来定义一些函数如果它不存在。在这种情况下，文件和 class 可能需要不同的 @author 标签。
如果您担心清晰度或发现提供更多详细信息有帮助，请将其放在两个地方；它不会伤害。就个人而言，如果我要添加 @author 标签，我会将它们添加到每个文件 和 几乎每个重要的代码块。如果 class 有可能在未来的某个时候变成接口或抽象 class，那么这种方法是有意义的。
例如，您可能有一个由 Joe 创建的 class DatabaseConnector，它连接到 MySQL 数据库。随着时间的推移，您决定使其更加抽象，以便用户也可以使用 PostgreSQL。所以，Bob 将 DatabaseConnector 变成了抽象的 class，而 Joe 的原始代码变成了新的 class、DatabaseConnectorMySQL 的一部分。 Joe 仍然是 DatabaseConnector.php 和 DatabaseConnectorMySQL 中所有代码的 @author，但 Bob 编写了当前 DatabaseConnector 中的所有代码。因此，无论是为了在适当的时候给予信任，还是为了告诉人们有问题时应该联系谁，您都想显示谁写了什么以及谁负责某些选择（例如方法名称）。
或者，也许您觉得这样太过分而且会增加混淆，您宁愿在文档块的其他地方解释历史。或者您可能根本不关心 @author 标签，因为您需要的所有信息都存储在您的版本控制存储库中（例如，git blame）。由你决定;这里没有错误答案。