Документирование тем и модулей

При разработке модулей/тем для Open Source проектов вообще и Drupal в частности — хорошая документация сделанная разработчиком и идущая вместе с модулем/темой очень важна. Есть хорошие книги по кодированию и у каждого кодера есть свой опыт и своё мнение о том, какой должна быть документация к коду. Ниже находится набор рекомендаций по вопросу того, как писать документацию к модулям и темам в Drupal.

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

Рекомендации

• Пишите файл README. Все модули и темы (за исключением очень простых) должны включать файл README.txt. Этот файл должен включать обзор основных возможностей модуля/темы и описывать как и для чего можно использовать модуль/тему. Это файл может повторять своё описание на странице проекта на drupal.org. Также можно использовать прямую ссылку на README используя подобную ссылку: http://cvs.drupal.org/viewvc.py/drupal/contributions/modules/modulename/README.txt?view=co. Файл README.txt должен нести достаточно информации для того, чтобы пользователь мог сделать вывод о нужности этого модуля/темы до скачивания и установки.
• Используйте hook_help(). Все модули (за исключением очень простых) должны использовать hook_help(). По вопросу того, какую использовать структуру для документации, смотрите статью Embedded documentation style guide. В качестве альтернативы, вы можете включить в код вызов README.txt:
  
  <?php
/**
* Implementation of hook_help().
*/
function mymodule_help($section) {
  switch ($section) {
    case 'admin/help#mymodule':
      // Return a line-break version of the module README
      return filter_filter('process', 2, NULL, file_get_contents( dirname(__FILE__)."/README.txt") );
  }
}
?>

  Страница Help в Drupal — очевидное место для получения справки.

• Опишите пользователю что модуль делает. Файл README.txt и другие справочные файлы должны описывать как получить доступ к возможностям модуля. Хорошо в этих файлах указать какие модуль создаёт пункты в меню, перечислить адреса по которым можно найти настройки этого модуля, чтобы пользователь не искал их в поте лица по всему сайту. Если модуль изменяет существующие UI формы, использует Form API — скажите пользователю о том, как всё это должно выглядеть когда модуль правильно работает. Если модуль требуется настроить, укажите ссылку на страницу настроек этого модуля и по возможности сделайте краткую справку с чего стоит начать.
• Подумайте о названии секции для модуля. В вашем файле module.info вы можете определить принадлежность модуля к определённой секции. Для большинства модулей это не требуется. Используйте эту возможность только если ваш модуль дополняет крупные пакеты, такие как: CCK, Views, Organic groups, e-Commerce и т.д.
• Хорошо документируйте все функции. Желательно, если вы будете выполнять требования стиля комментирования Doxygen. Несмотря на то, что иногда это кажется мукой, научитесь любить это дело, поскольку справочная система api.drupal.org использует комментарии для генерации документации. Также, многие средства разработки (IDEs) могут автоматически определять блоки документации Doxygen и генерировать контекстную справку. И всё это не считая удобства для людей, которые будут работать с вашим кодом.