Вопрос: Существует ли общепринятый синтаксис phpDoc для документирования, какой хук вызывает функцию?

Я храню все хуки в одном файле, а функции организованы в соответствующие классы (разные автоматически загружаемые файлы).

В поисках стандартного способа документировать, что единственная цель функции - вызываться, например, по 'init'.

В настоящее время используется @see 'init'

Спасибо!

Пример кода

hooks.php 

  add_action ('init', 'remove_image_sizes');

functions.php 

  /** * Удаляет размеры изображений, добавленные по ошибке до 1.6.18 * * @since 1.6.18 * @see 'init' * @return void * /function remove_image_sizes () {remove_image_size ('foo'); remove_image_size ('bar');}
Ответов: 1 Создан 15-02-2018 04:12 Curtis

Ответы и комментарии:

Я использую @ wp-hook, но, насколько мне известно, стандарта нет.
Создан 15-02-2018 04:57 fuxia♦
Существует формат, используемый в самом WP Core, который я бы рекомендовал, описание которого было бы хорошим ответом.
Создан 15-02-2018 04:40 Tom J Nowell♦
Функция doc block должна документировать, что он делает, для чего он может быть полезен, но не кто его использует. Имеет смысл документально подтвердить, что он был разработан с учетом хуков X, но это так.
Подумайте о модульном тестировании. В этом контексте вы, скорее всего, будете вызывать функцию самостоятельно, не выполняя инициализацию всего ядра, что означает, что описание, связывающее функцию с крючком init, будет по меньшей мере вводить в заблуждение.
Стиль, который вы пытаетесь использовать, также заставит вас изменять документацию при изменении неактуального кода, например, если вы решите переместить вызов в wp_loaded вместо init
Создан 15-02-2018 04:26 Mark Kaplun20.2k52754