Как мне документировать вызовы функций?

Чтение Стандарты документации WordPress для PHP , Я не вижу нигде, где упоминается, как документировать вызов функции, например add_action( 'foo', 'bar' );

Должен ли я документировать вызовы функций, и если да, то как?

5 голосов | спросил henrywright 25 FebruaryEurope/MoscowbWed, 25 Feb 2015 01:24:24 +0300000000amWed, 25 Feb 2015 01:24:24 +030015 2015, 01:24:24

2 ответа


4

Вы не документируете вызовы функций, а определения функций. Потому что эту функцию можно назвать неограниченным временем, верно? Поэтому нет смысла документировать функции при их вызове.

Если вы документируете вызов, то, вероятно, потому, что вы делаете некоторые вещи, которые хотите запомнить позже, или пусть другие разработчики знают. Но, как правило, я бы сказал, что этого не должно быть - в идеальном мире.

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

add_action( 'foo', 'bar' );

Где foo - это крючок и bar является функцией. Для этого вам, вероятно, придется пойти на него, как @birgire показывает это в своем ответе.

Я предполагаю, что вы знаете, как документировать функцию, вы связали правильный документ. Там вы найдете два раздела о документировании перехватов, которые, по-видимому, применимы только к do_action() и apply_filters()

    /**
     * Резюме.
     *
     * Описание.
     *
     * @since x.x.x
     *
     * @param type $ var Описание.
     * @param array $ args {
     * Краткое описание об этом хеше.
     *
     * @type type $ var Описание.
     * @type type $ var Описание.
     *}
     * @param type $ var Описание.
     * /
/** Это действие документировано в path /to /filename.php * /

Это официальная часть.

Лично нравится добавлять что-то вроде этого:

/**
 * (Here is the official part)
 *
 * @hooked bar - 10
 */
do_action( 'foo' );

Я делаю это на последних штрихах проекта, потому что считаю его полезным и информативным. Я не придумал этого, но не спрашивай меня, откуда он, может быть, из туалета. Кроме того, я хотел бы отметить, что это, вероятно, не очень хорошая практика. Схема здесь

@hooked function_name - priority
ответил Nicolai 25 FebruaryEurope/MoscowbWed, 25 Feb 2015 02:27:03 +0300000000amWed, 25 Feb 2015 02:27:03 +030015 2015, 02:27:03
5

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

/wp-includes/default-filters.php

настройка подключения к компьютеру .

Снимая этот файл, мы видим, что на вызов функции не более одной строки комментариев:

// Slugs
add_filter( 'pre_term_slug', 'sanitize_title' );

Некоторые вызовы сгруппированы по комментарию:

// Mime types
add_filter( 'pre_post_mime_type', 'sanitize_mime_type' );
add_filter( 'post_mime_type', 'sanitize_mime_type' );

или даже так:

// Format text area for display.
foreach ( array( 'term_description' ) as $filter ) {   
        add_filter( $filter, 'wptexturize'  );
        add_filter( $filter, 'convert_chars'    );
        add_filter( $filter, 'wpautop'          );
        add_filter( $filter, 'shortcode_unautop');
}

Поэтому я предлагаю вам сделать то, что имеет смысл для вашего кода, и помогает сделать его более читаемым.

Мы также можем улучшить читаемость с помощью описательных обратных вызовов. Например:

// BAD:
add_filter( 'the_title', 'wpse_11' );

// BETTER:
add_filter( 'the_title', 'wpse_remove_blacklisted_words' );
ответил birgire 25 FebruaryEurope/MoscowbWed, 25 Feb 2015 02:44:51 +0300000000amWed, 25 Feb 2015 02:44:51 +030015 2015, 02:44:51

Похожие вопросы

Популярные теги

security × 330linux × 316macos × 2827 × 268performance × 244command-line × 241sql-server × 235joomla-3.x × 222java × 189c++ × 186windows × 180cisco × 168bash × 158c# × 142gmail × 139arduino-uno × 139javascript × 134ssh × 133seo × 132mysql × 132