描述

Question

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

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

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

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

一些例子： 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）似乎不使用文件级doc块中的@author标记，而是专门使用类级doc块。但接下来我浏览的那些例子包括类声明。

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将在尖括号之间采用任何文本

（＆lt; and＆gt;）

并尝试将其解析为电子邮件地址。如果成功，将在页面中显示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.php的@author和DatabaseConnectorMySQL中的所有代码，但Bob编写了当前DatabaseConnector中的所有代码。因此，无论是为了给予应有的信用还是告诉与谁有联系的人，如果他们有问题，你想要表明谁写了什么以及谁负责某些选择（比如方法名称）。

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

phpDocumentor / ApiGen @author标签位置

1 个答案:

描述

实施例