Сделайте ваши плагины для WordPress еще более удобными для разработчиков

В прошлой статье мы рассмотрели, как Действия и Фильтры могут быть добавлены в ваши плагины WordPress, чтобы сделать их удобными для разработчиков.

Сегодня мы рассмотрим, как предоставить документацию для разработчиков.

Документирование ваших действий и фильтров

Полезно задокументировать действия и фильтры вашего плагина WordPress, чтобы разработчики могли быстро найти то, что им нужно, а также понять, что делает каждое действие и фильтр.

Комментирование кода

Как разработчики, мы вполне можем просматривать чужой код, чтобы понять, как что-то работает. Добавление комментариев DocBlock к нашим действиям и фильтрам — отличный способ объяснить, что делает конкретный вызов:

/**
 * Helper method to retrieve schedule options
 *
 * @since 3.0
 *
 * @return array Schedule Options
 */
static public function get_schedule_options() {

    // Build schedule options
    $schedule = array(
        'queue_bottom'  => __( 'Add to End of Buffer Queue', 'wp-to-buffer-pro' ),
        'queue_top'     => __( 'Add to Start of Buffer Queue', 'wp-to-buffer-pro' ),
        'now'           => __( 'Post Immediately', 'wp-to-buffer-pro' ),
        'custom'        => __( 'Custom Time', 'wp-to-buffer-pro' ),
    );

    /**
     * Returns filtered schedule options
     *
     * @since 3.0
     *
     * @param array $schedule Schedule Options
     * @return array Filtered Schedule Options
     */
    return apply_filters( 'wp_to_buffer_pro_get_schedule_options', $schedule );

}

Для более сложных действий и фильтров, которые являются частью более крупного вызова функции, это действительно полезно, поскольку может быстро объяснить передаваемые переменные:

 /**
* Returns an image link if the original source cannot be found.
*
* @since 1.0.0
*
* @param string $item['link'] Image Link
* @param int    $id           Image Attachment ID
* @param array  $item         Image Data
* @param array  $data         Gallery Data
* @return string              Image Link
*/
return apply_filters( 'envira_gallery_no_image_src', $item['link'], $id, $item, $data );

Онлайн документация

Наличие единой точки отсчета для всех действий и вызовов фильтров поможет разработчикам быстро найти то, что им нужно. Мы можем скопировать и вставить каждый apply_filtersdo_action

Однако, если действия и фильтры вашего плагина распределены по нескольким файлам, потребуется время, чтобы объединить все это в один документ. Нам также придется вручную повторить этот процесс, если мы когда-нибудь добавим новые действия или фильтры.

К счастью, есть плагины WordPress, которые могут помочь автоматизировать этот процесс. В частности, плагин Extract Filters and Actions позволяет нам выбрать установленный плагин WordPress и создавать HTML-таблицы действий и фильтров. Затем они могут быть скопированы в онлайн-документацию.

Для настройки Extract Filters and Actions вам понадобится установка WordPress, которая также содержит плагин, из которого вы хотите прочитать действия и фильтры.

В области администрирования WordPress перейдите к «Плагины»> «Добавить новый» и выполните поиск «Извлечь фильтры и действия». Затем нажмите « Установить сейчас» для плагина « Извлечение фильтров и действий из плагинов» :

После установки активируйте плагин и начните использовать его, перейдя в «Плагины»> «Извлечь фильтры и действия»:

Есть несколько параметров для настройки перед генерацией документации: