Что подразумевается под тегом @file в dockblock

Question

Я использую phpCheckstyle phpcheckstyle для стандартизации моего комментирования кода. После проверки файла в предупреждении предлагается "Комментарии блока документа должны содержать информацию о файле (@file) для каждого файла PHP". Предупреждение разрешается при добавлении тега @file - я хочу знать, какое значение следует назначить этому тегу (Что это показывает).

И в чем разница между @file и @filesource?

Спасибо,

Answer 1

Согласно стандартам кодекса @file это Doc-Block комментарий (для каждого файла) и описание того, для чего предназначен этот файл.

Например, представьте файл вашей модели Users.php со всеми его методами, ну, вы можете поместить в свой комментарий к файлу что-то вроде этого:

/**
 @file
   This file will store all model methods to recover/update/delete Users.php
 ....
*/

@filesource, afaik, похож на тег @example, вы можете посмотреть документацию по грушам здесь

Answer 2

@fileне является распознаваемым тегом .

По иронии судьбы трудно найти документацию по этому вопросу и ориентироваться в ней.

Но https://pear.php.net/package/PhpDocumentor/docs/latest/phpDocumentor/tutorial_tags.pkg.html предполагает, что DocBlock для файла будет первым DocBlock в файле:

Пример:

       1. /**
2.  * tags demonstration
3.  * @author this tag is parsed, but this @version tag is ignored
4.  * @version 1.0 this version tag is parsed
5.  */

… и что нет необходимости специально аннотировать это как таковое.