phpDocumentor / ApiGen @author标签位置

Question

I would love to post this as a general programming question. The reason I don't is that different documenting systems handle tags differently and therefore impose their own rules on what is "right" or "wrong" for a specific language.

Now the language in question is PHP. Which does not have a "standard" documentation system as of now. There is phpDocumentor, which while outdated as a project appears to have established the base. Current products like ApiGen seem to make an effort to support its syntax.

One tag I don't quite know where to put is the @author tag. I feel like placing it with the file level doc block. Together with @copyright, @license, @package and @link. Instead of inside the class level doc block. For some context: my PHP files contain one class declaration each only.

However, I failed to find the evidence supporting this to be an accepted standard. There is indeed little information to be found which location should be preferred. Which led me to believe that possibly I should include this information in both the file level doc block as well as the class level one.

Some examples: OpenEMR appears to prefer using @author both inside the file level block as well as the class level one (http://www.open-emr.org/wiki/index.php/How_to_Document_Your_Code_Properly). The document does not specify whether that is intended to happen at the same time or only if the file does not contain a class but rather a number of functions:

/**
 * 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 <[e-mail]>
 *
 * 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 <[e-mail]>
 * @author  Brady Miller <[e-mail]>
 * @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
{

}

The two projects referenced by ApiGen however (Doctrine ORM API and Nette API) don't seem to use the @author tag in the file level doc block but exclusively with the class level doc block. But then the only examples I saw when browsing where those including class declarations.

Doctrine is using @author along with other tags, I would have thought placing in the file level doc block, inside the class level doc block (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 <[e-mail]>
 * @author  Guilherme Blanco <[e-mail]>
 * @author  Jonathan Wage <[e-mail]>
 * @author  Roman Borschel <[e-mail]>
 * @author  Konsta Vesterinen <[e-mail]>
 */
abstract class AbstractQuery
{ ... }

Nette, while also only using the @author tag in a class/interface context, does not appear to use @license @copyright or @link at all:

/**
 * 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

You can use it to document any element, so use it wherever it is appropriate and helpful for your needs.

From the manual:

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>[e-mail]</strong>
 * , where underlined text is a "mailto:[e-mail]" link
 * @author Gregory Beaver <[e-mail]>
 */
/**
 * function datafunction
 * another contributor authored this function
 * @author Joe Shmoe
 */
function datafunction()
{
...
}

Edit to clarify: Most times, a class is in a file by itself, so the file and class author are the same. So, you could have just one @author tag, in the file-level block. But not always: maybe the file was automatically generated by the project team as a placeholder, and a different author implemented it, or maybe there's some additional code in the file, like a one-time if statement to define some function if it doesn't already exist. In that case, the file and class may need different @author tags.

If you're concerned about clarity or find it helpful to have more detail, put it in both places; it can't hurt. Personally, if I'm adding @author tags, I'm going to add them to every file and pretty much every significant block of code. This approach makes sense if there's any chance a class will get turned into an interface or abstract class at some point down the road.

As an example, maybe you have a class DatabaseConnector, created by Joe, that hooks up to a MySQL database. As time goes on, you decide to make it more abstract so users can also use PostgreSQL. So, Bob turns DatabaseConnector into an abstract class, and Joe's original code becomes part of a new class, DatabaseConnectorMySQL. Joe is still the @author of DatabaseConnector.php and of all of the code in DatabaseConnectorMySQL, but Bob wrote all of the code currently in DatabaseConnector. So, both for giving credit where due and for telling people whom to contact if they have questions, you want to show who wrote what and who is responsible for certain choices (like method names).

Or, maybe you feel like that's just too much and adds confusion, and you'd rather just explain the history elsewhere in the docblock. Or maybe you don't care about @author tags at all, because all the info you need is stored in your version control repository (e.g., git blame). It's up to you; there is no wrong answer here.