Странные комментарии над объявлениями функций PHP

Question

Я заметил, что у многих скриптов есть комментарии такого типа:

/**
 * Retrieve list of themes with theme data in theme directory.
 *
 * The theme is broken, if it doesn't have a parent theme and is missing either
 * style.css and, or index.php. If the theme has a parent theme then it is
 * broken, if it is missing style.css; index.php is optional. The broken theme
 * list is saved in the {@link $wp_broken_themes} global, which is displayed on
 * the theme list in the administration panels.
 *
 * @since 1.5.0
 * @global array $wp_broken_themes Stores the broken themes.
 * @global array $wp_themes Stores the working themes.
 *
 * @return array Theme list with theme data.
 */
function get_themes() {
    global $wp_themes, $wp_broken_themes;

    ...

    return $wp_themes;
} 

Похоже, что-то вроде документации для функции, но что там со словами, начинающимися с @?

Например, @since, @global, @return, @access, @param и т. Д. ...?

Я знаю, что они имеют в виду, но почему перед ними стоит @?Нужно ли им идентифицировать себя с каким-то приложением документации ??1009*

Answer 1

Это стандарт JavaDoc.Скорее всего, автор выбрал его, потому что большинство IDE автоматически форматируют его красиво.

http://en.wikipedia.org/wiki/Javadoc

Answer 2

Это PHPDoc , который является адаптацией любимого формата Javadoc.

Эти форматы документации несколько более читабельны благодаря их принудительной согласованности и полезны для IDE и генераторов автоматической документации, таких как phpdoc .

Answer 3

Нужно ли им идентифицировать себя с каким-нибудь приложением к документации?

Они полезны с автоматическими документаторами, такими как phpDocumentor , и в целом являются хорошим способом документировать ваш код. Как указал васаби , IDE также могут их использовать и делать некоторые полезные для вас вещи, например, предложения типа аргумента функции.

Даже если вы не документируете свой код, это хорошая привычка - просто не чувствуйте необходимости увлекаться им в некоторых людях (документируя все возможные вещи).

Answer 4

Это определенно PHP Documentator .Части «@something» используются для добавления информации в документацию.Пожалуйста, смотрите документацию PHP Documentator для подробностей - в ней даже есть инструмент для генерации файлов документации из комментариев ( здесь ) в формате PHP Documentator.

Надеюсь, что это поможет вам.

Answer 5

Похоже, phpDocumentor , что, более или менее, JavaDoc для PHP.