phpDocumentor/ApiGen @author tag location

Question

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

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

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

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

Некоторые примеры: OpenEMR, по-видимому, предпочитает использовать @author как внутри блока уровня файла, так и уровня уровня 1 (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 <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 в блоке doc уровня файла, но исключительно с блоком doc класса класса. Но тогда были единственные примеры, которые я видел, когда просматривали те, которые включали объявления классов.

Учение использует @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 <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 будет принимать любой текст между угловыми скобками

(< и>)

и попытаться разобрать его как адрес электронной почты. В случае успеха он будет отображаться с ссылкой mailto на странице NEW v1.2 - @author теперь унаследован дочерними классами из родительского класса, см. Inline {@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 для определения некоторой функции, t уже существуют. В этом случае для файла и класса могут потребоваться разные теги @author.

Если вы обеспокоены ясностью или считаете полезным, чтобы иметь более подробную информацию, поместите его в оба места; это не может повредить. Лично, если я добавляю теги @author, я собираюсь добавить их в каждый файл и почти каждый значительный блок кода. Этот подход имеет смысл, если есть шанс, что класс будет превращен в интерфейс или абстрактный класс в какой-то момент по дороге.

В качестве примера, может быть, у вас есть класс DatabaseConnector, созданный Джо, который подключается к базе данных MySQL. Со временем вы решите сделать его более абстрактным, чтобы пользователи могли также использовать PostgreSQL. Итак, Боб поворачивает DatabaseConnector в абстрактный класс, а исходный код Джо становится частью нового класса, DatabaseConnectorMySQL. Джо по-прежнему является @author DatabaseConnector.php и всего кода в DatabaseConnectorMySQL, но Боб написал весь код в настоящее время в DatabaseConnector. Таким образом, как для предоставления кредита в случае необходимости, так и для общения с людьми, с которыми можно связаться, если у них есть вопросы, вы хотите показать, кто написал, кто и кто несет ответственность за определенные выборы (например, имена методов).

Или, может быть, вы чувствуете, что это слишком много, и добавляет путаницу, и вы просто просто объясните историю в другом месте в докблоке. Или, может быть, вам вообще не нужны теги @author, потому что вся необходимая информация хранится в вашем репозитории управления версиями (например, git blame). Тебе решать; здесь нет неправильного ответа.