phpDocumentor / ApiGen @author расположение тегов

Я хотел бы опубликовать это как общий вопрос программирования. Причина, по которой я этого не делаю, заключается в том, что разные системы документирования обрабатывают теги по-разному и поэтому устанавливают свои собственные правила относительно того, что является «правильным» или «неправильным» для конкретного языка.

Теперь речь идет о PHP. Который не имеет «стандартной» системы документации на данный момент. Есть phpDocumentor, который, хотя и устарел как проект, похоже, создал базу. Современные продукты, такие как ApiGen, стараются поддерживать его синтаксис.

Один тег, который я не знаю, куда поместить, это тег @author. Я чувствую, как поместить его с блоком документа уровня файла. Вместе с @copyright, @license, @package и @link. Вместо того, чтобы внутри блока документации уровня класса. Для некоторого контекста: мои PHP-файлы содержат только одно объявление класса.

Однако мне не удалось найти доказательства, подтверждающие это, как принятый стандарт. Там действительно мало информации, чтобы найти, какое место должно быть предпочтительным. Это заставило меня поверить, что, возможно, мне следует включить эту информацию как в блок документации на уровне файлов, так и на уровне класса.

Некоторые примеры:
OpenEMR предпочитает использовать @author как внутри блока уровня файла, так и на уровне класса (http://www.open-emr.org/wiki/index.php/How_to_Document_Your_Code_Properly). В документе не указывается, должно ли это происходить одновременно или только в том случае, если файл не содержит класс, а скорее ряд функций:

/**
* 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 <[email protected]>
*
* 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 <[email protected]>
* @author  Brady Miller <[email protected]>
* @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 <[email protected]>
* @author  Guilherme Blanco <[email protected]>
* @author  Jonathan Wage <[email protected]>
* @author  Roman Borschel <[email protected]>
* @author  Konsta Vesterinen <[email protected]>
*/
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
{...}