Объектно-ориентированное программирование в WordPress: документируйте плагин I

22 января 2018

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

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

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

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

    В Введение Классы Типы Создание структур: Условные выражения Системы управления: Циклы Функции и атрибуты Scope Построение плагина I Построение плагина II

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

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

Стандарты документации WordPress для PHP

Для начала WordPress Codex содержит руководство специально для стандартов документации PHP. Вы можете полностью ознакомиться со стандартами; однако мы собираемся выделить наиболее важные функции того, что мы будем внедрять в следующей статье.

Основными вещами, которые мы имеем дело с документацией, являются следующие:

File Заголовки Inline требуют операторов Определения кластеров и функций Variable или свойства класса

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

Итак, с учетом сказанного, давайте начнем.

Заголовки файлов

Заголовки файлов уникальны в том, что они являются тем, что должно быть помещено в каждый файл файлов, которые составляют плагин (или тему, но это не в центре внимания этой серии) но они не всегда.

В соответствии с Codex:

Блок заголовка файла PHPDoc используется, чтобы дать обзор того, что содержится в файле.

Общий шаблон, который мы будем использовать, начиная с следующей статьи, выглядит следующим образом::

/**
 * Short Description (no period for file headers)
 *
 * Long Description.
 *
 * @link URL
 * @since x.x.x (if available)
 *
 * @package WordPress
 * @subpackage Component
 */

Обратите внимание, что в заголовках файлов мы не включаем период и есть два компонента описания:

    А краткое описание Достаточное описание

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

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

Inline require Statement

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

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

Например:

/**
 * Short description. (use period)
 */
require_once( ABSPATH . '/filename.php' );

Однако обратите внимание, что в соответствии с Кодексом это не ограничивается только вызовами функций, такими как require_once.

Необходимые или включенные файлы должны быть документированы с помощью краткого описания блока PHPDoc. При желании это может быть применимо для вызовов inline get_template_part (), необходимых для ясности.

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

Определения классов и функций

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

Определения классов

Определения классов - это комментарии кодов, которые появляются между заголовками файлов (которые мы обсуждали выше) и имя класса.

Формат, который используется для документирования класса, выглядит следующим образом:

/**
 * Short description. (use period)
 *
 * Long description.
 *
 * @since x.x.x
 *
 * @see Function/method/class relied on
 * @link URL
 */

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

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

Определения функций

Подобно определениям классов, которые вы можете ожидать, чтобы увидеть следующее:

/**
 * Short description. (use period)
 *
 * Long description.
 *
 * @since x.x.x
 * @access (for functions: only use if private)
 *
 * @see Function/method/class relied on
 * @link URL
 * @global type $varname Short description.
 *
 * @param  type $var Description.
 * @param  type $var Optional. Description.
 * @return type Description.
 */

Обратите внимание, что в комментарии к коду выше, очень мало различий в том, что мы видели с документацией классов.

В дополнение к тому, что указано выше, мы видим информацию для:

global переменных parameters return types

Очевидно, что это материал, который обычно не используется в контексте класса; однако он используется в контексте функции.

С этой целью, вот как вы можете думать о каждом из перечисленных выше:

global переменные относятся к тем переменным, которые используются в контексте функции, глобальной для среды WordPress. Это включает в себя такие вещи, как $ post, $ authordata и другие, перечисленные здесь.
Тетка @param ссылается на переменные, которые принимает функция. Очевидно, что это включает тип переменной, которую он принимает, и описание того, что представляет переменная.
Тетка @return обсуждает тип переменной, возвращаемой функцией, и краткое описание того типа данных, который является Верно.

Вместо того, чтобы приводить конкретный пример этого здесь, мы сделаем это в последующей записи с кодом, который мы написали в предыдущем сообщении.

Свойства переменных или классов

Наконец, свойства переменных - или более известные как свойства класса (которые иногда называются атрибутами) - представляют данные, которые хранятся внутри класса.

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

Как видно из предыдущей статьи, свойства класса определяются сразу после имени класса и перед конструктором (независимо от того, являются ли они общедоступными или частными).

Чтобы документировать эти атрибуты, мы следуем следующему шаблону:

/**
 * Short description. (use period)
 *
 * @since x.x.x
 * @access (private, protected, or public)
 * @var type $var Description.
 */

Достаточно легко понять.

Некоторые могут утверждать, что использование @access является фривольным, поскольку модификатор доступа функции, непосредственно следуя комментарию, объясняет тип функции.

Но здесь различия в стандартах документации WordPress отличаются от некоторых стандартов PHP (как на месте, так и тех, которые находятся в процессе стандартизации).

Слово о стандартах PSR

Короче говоря, PSR ссылается на стандартные рекомендации PHP, предложенные группой PHP Framework Interop.

Здесь вы можете прочитать о каждом из этих стандартов:

PSR-0: стандарт автозагрузки PSR-1: стандарт базового кодирования PSR-2: руководство по стилю кодирования PSR -3: Интерфейс ведения журнала PSR-4: Автозагрузчик

Какой PSR-5 обсуждается прямо сейчас. Они важны для всех разработчиков PHP независимо от платформы или фундамента, которые они используют, но я также считаю, что стоит отметить различия (и сходства) между PSR и стандартами WordPress, так как существуют различия.

Что мы выбираем?

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

Это не означает, что мы не должны пытаться более тесно увязываться с тем, что делает более крупное сообщество PHP; однако, если мы напишем код WordPress для других разработчиков WordPress, то это то, на чем мы должны в первую очередь сосредоточиться.

Следующее Следующее

В следующей статье мы рассмотрим применение вышеуказанных принципов в контексте нашего плагина.

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

Тем временем не стесняйтесь оставлять любые вопросы и комментарии в ленте ниже!