Документирование шаблонов

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

Под катом пара наглядных примеров документации к шаблонам.

В наших собственных проектах мы пишем встроенные доки к исходному коду (phpDocumentor), но
почему-то шаблоны игнорируем, а ведь это так просто!

На момент создания шаблона мы прекрасно знаем его назначение и данные,
которые туда передаются.

Добавив такие доки, можно сэкономить время верстальщиков и собственное.

Пример 1: шаблон list.tpl

{* 
  Список постов
 
  Используется в: BlogModule::listAction 
  Передаваемые переменные:
    $returnedInfo array посты [ { id : 447, title : 'тайтл', ...}  ]
    $pager AE_Pager объект постраничной навигации
    $admin boolean админ/не админ
    $years array [2010,2009,2008]
    $months array { апрель : 4, март : 3, февраль : 2 }
    $selectedYear год или null (если "Все")
    $selectedMonth месяц или null (если "Все")
*}
 
{if $admin}
  <button class="button" onClick="window.location='/{$SECTION}/addNews'">Добавить запись</button>
{/if}
 
{foreach key=cid item=con from=$returnedInfo}
…
{/foreach}

Пример 2: в нотации phpDocumentor:

{* 
  Список постов
 
  Особенности и нюансы, примечания и другие подробности в этом абзаце
  @see BlogModule::listAction 
  @param array $returnedInfo посты [ { id : 447, title : 'тайтл' } ]
  @param AE_Pager $pager  объект постраничной навигации
  @param boolean $admin админ/не админ
  @param array $years [2010,2009,2008]
  @param array $months { апрель : 4, март : 3, февраль : 2 }
  @param mixed $selectedYear год или null (если "Все")
  @param mixed $selectedMonth месяц или null (если "Все")
*}
 
 
{if $admin}
  <button class="button" onClick="window.location='/addNews'">Добавить запись</button>
{/if}
 
{foreach key=cid item=con from=$returnedInfo}
…
{/foreach}

Как правильно документировать массивы

Есть еще одна проблема: phpDocumentor не говорит в каком виде писать доку к массивам,
и разработчики не редко игнорируют ее:

   @param array $returnedInfo массив постов

Не очень информативно, согласитесь?

Для себя, я решил, что удобно в доке приводить пример массива в JSON нотации:

  @param array $years [2010,2009,2008]
  @param array $months { апрель : 4, март : 3, февраль : 2 }

Почему JSON? Потому что компактнее, и для меня читабельнее.

Как вариант, могу предложить синтаксис PHP:

  @param array $years array(2010,2009,2008)
  @param array $months  array( 'апрель' => 4, 'март' => 3, 'февраль' => 2 )

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