@package и @subpackage: как использовать в дочерних темах WordPress

Question

@package и @subpackage: как использовать в дочерних темах WordPress

23 янв. 2013 г., 16:44:36

Просмотры: 14.1K

Голосов: 8

У меня проблема с тегами @package и @subpackage.

Я перешел по предложенной ссылке (Для чего нужны package и subpackage в комментариях?). Там я не нашел ничего, что могло бы помочь мне с моей проблемой, только этот ответ: "Это теги PHPDoc - они используются для генерации осмысленной (и автоматизированной) документации к коду". Вот что у меня сейчас:

/**

* Содержит список всех пользовательских хуков действий и соответствующих функций, определенных для abc.

* Этот файл подключается в functions.php:

*

* @package theme-name

* @subpackage Functions

*/

Это не дочерняя тема twenty ten. В папке theme-name есть папка: functions. Моя дочерняя тема находится в другой папке. Я сохранил файл functions.php в папку моей дочерней темы. Ничего не происходит (изменение содержимого), независимо от того, меняю ли я subpackage на имя моей папки или оставляю слово Functions.

Что я должен указать здесь?

/**

* Содержит список всех пользовательских хуков действий и соответствующих функций, определенных для abc.

* Этот файл подключается в functions.php:

*

* @package theme-name

* @subpackage ???

*/

Marie

81

дочерняя тема

Все ответы на вопрос

Комментарии

Привет, Спасибо всем за ответы. Я оставил название пакета таким же, как название моей темы (надеюсь, я правильно понял).

Мой .php файл находится в папке functions в дочерней теме, так же как и в родительской теме. У меня не получается заставить его работать, поэтому я подумал, что проблема в том, как package и subpackage ссылаются на другие элементы.

Судя по вашим словам, это не так, но файл всё равно не работает. Как мне заставить .php файл работать? (Или стоит создать новую тему обсуждения?)

Marie

24 янв. 2013 г. 01:35:27

Вы используете include() или require() в вашем основном файле functions.php для подключения нового PHP файла? Если нет, то он никогда не будет загружен. Я бы посоветовал создать новую тему, но подключение PHP файлов - это не специфичная для WP проблема; поэтому если вы всё же создадите новую тему, я бы рекомендовал сделать это на Stack Overflow.

EAMann

24 янв. 2013 г. 17:48:59

Chip Bennett 55.1K · Answer 1 · 2013-01-23T17:13:28Z

Эмпирическое правило: ваш код поставляется в составе (т.е. упакован) с кодом, указанным в @package? Если нет, то вы используете некорректное значение для @package.

Для большинства тем это просто:

Темы, входящие в ядро, используют @package: WordPress и @subpackage Theme-Name, потому что они поставляются и распространяются вместе с самим WordPress
Все остальные темы используют @package: Theme-Name, потому что они поставляются и распространяются отдельно от WordPress.

Все темы являются слоем абстракции самого WordPress и зависят от WordPress для своего вывода. Но эта зависимость не делает их @subpackage WordPress.

Я бы применил это правило и к дочерним темам. Они являются самостоятельными пакетами, которые поставляются и распространяются отдельно от родительской/шаблонной темы, на которой они основаны.

EAMann 32.2K · Answer 2 · 2013-01-23T16:59:17Z

Как и сказано в оригинальной документации, это теги PHPDocumenter. Они никак не влияют на ваш код, поэтому их изменение ни на что не повлияет.

Однако они полезны для автоматизированных инструментов, которые анализируют ваш код и создают удобочитаемую документацию. Например, этот PHPXref — это пример разобранной версии WordPress.

В WordPress @package обычно указывается как WordPress. @subpackage — это модуль, который вы рассматриваете. Например, в начале класса WP_Http можно увидеть:

/**
 * Простой и единообразный API для HTTP-запросов.
 *
 * Стандартизирует HTTP-запросы для WordPress. Обрабатывает куки, кодирование и декодирование gzip,
 * декодирование чанков, если используется HTTP 1.1, а также различные другие сложные реализации HTTP-протокола.
 *
 * @link http://trac.wordpress.org/ticket/4779 Предложение HTTP API
 *
 * @package WordPress
 * @subpackage HTTP
 * @since 2.7.0
 */

В вашем случае @package будет именем вашей темы. @subpackage необязателен и актуален только если у вас есть другие модули внутри темы — ваш файл functions.php не является подпакетом темы, поэтому я бы опустил этот тег.

Дочерние темы также не обязаны наследовать структуру @package/@subpackage от родительских. Используйте то, что имеет смысл для вашего проекта, потому что, по сути, эти комментарии и пометки предназначены для помощи другим в понимании структуры вашего проекта.

bueltge 17.1K · Answer 3 · 2013-01-23T16:57:42Z

Тег @package используется для указания пакетов, в которые группируются классы, функции и определения, а также для определения темы в WordPress. Тег @subpackage является дочерним элементом темы, например, функциональность для конкретного требования или дочерняя тема, подпакет.

Небольшая подсказка по документации тегов phpdoc: http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html

bueltge

17.1K

23 янв. 2013 г. 16:57:42

s_ha_dum 65.5K · Answer 4 · 2013-01-23T17:02:13Z

Это теги документации. Они используются для группировки связанных частей кода с целью его документирования. В Википедии есть хорошая таблица с доступными тегами. Официальная документация находится на http://www.phpdoc.org/.

Ничего не происходит (изменение содержимого) ни при смене subpackage на имя моей папки, ни при оставлении слова "Functions" там.

Верно. Ничего не происходит. Это предназначено только для документации кода. Вы не заметите никаких изменений, пока не запустите ваш код через скрипт PHPDoc, который сгенерирует документацию, но не изменит работу вашего кода.

Используйте @package для идентификации вашей темы. Используйте @subpackage, если хотите, для группировки функций внутри темы — например, файл, содержащий виджеты, специфичные для темы.

Какая разница, включать аннотацию @package или нет?

http://codex.wordpress.org/Inline_Documentation