Documenting templates

Documentation is good! It allows you to save time and work harmoniously on people in a team. The documentation built into the code is doubly good, it is where it is needed and you don’t have to go far to write it.

Under the cut are a couple of illustrative examples of template documentation.

In our own projects we write embedded docks to the source code (phpDocumentor), but
For some reason, templates are ignored, but it's so easy!
')
At the time of creating the template, we know very well its purpose and data,
which are transferred there.

By adding such docks, you can save time and your own web designers.

Example 1 : list.tpl template

{*
List of posts

Used in: BlogModule :: listAction
Transmitted Variables:
$ returnedInfo array posts [{id: 447, title: 'title', ...} ]
$ pager AE_Pager pagination object
$ admin boolean admin / non admin
$ years array [2010,2009,2008]
$ months array { April: 4 , March: 3 , February: 2 }
$ selectedYear year or null (if all)
$ selectedMonth month or null (if All)
*}

{ if $ admin }
<button class = "button" onClick = "window.location = '/ {$ SECTION} / addNews'"> Add record </ button>
{ / if }

{ foreach key = cid item = con from = $ returnedInfo }
...
{ / foreach }

Example 2: in phpDocumentor notation:

{*
List of posts

Features and nuances, notes and other details in this paragraph
@see BlogModule :: listAction
@param array $ returnedInfo posts [{id: 447, title: 'title'} ]
@param AE_Pager $ pager pagination object
@param boolean $ admin admin / non admin
@param array $ years [2010,2009,2008]
@param array $ months { April: 4 , March: 3 , February: 2 }
@param mixed $ selectedYear year or null (if All)
@param mixed $ selectedMonth month or null (if "All")
*}


{ if $ admin }
<button class = "button" onClick = "window.location = '/ addNews'"> Add record </ button>
{ / if }

{ foreach key = cid item = con from = $ returnedInfo }
...
{ / foreach }

How to properly document arrays

There is another problem: phpDocumentor does not say in what form to write to the dock to arrays ,
and developers do not rarely ignore it:

    @param array $ returnedInfo an array of posts

Not very informative, agree?

For myself, I decided that it is convenient in the dock to give an example of an array in JSON notation:

   @param array $ years [2010,2009,2008]
   @param array $ months {April: 4, March: 3, February: 2}

Why json? Because it is more compact and readable to me.

Alternatively, I can offer PHP syntax:

   @param array $ years array (2010,2009,2008)
   @param array $ months array ('April' => 4, 'March' => 3, 'February' => 2)

Colleagues, do you document templates in your projects?
Are you confronted with the fact that the templates become very cumbersome and complex?