Bug 138998

Description Moty Keret 2006-04-27 12:59:34 EDT

DocBlock Templates

New for version 1.2.0, phpDocumentor supports the use of DocBlock templates.
The purpose of a DocBlock template is to reduce redundant typing. For instance,
if a large number of class variables are private, one would use a DocBlock
template to mark them as private. DocBlock templates simply augment any normal
DocBlocks found in the template block.

A DocBlock template is distinguished from a normal DocBlock by its header. Here
is the most basic DocBlock template:


1     /**#@+
2      *
3      */

The text that marks this as a DocBlock template is /**#@+ - all 6 characters
must be present. DocBlock templates are applied to all documentable elements
until the ending template marker:


0     /**#@-*/

Note that all 8 characters must appear as /**#@-*/ in order for phpDocumentor
to recognize them as a template. Here is an example of a DocBlock template in
action:


1     class Bob
2     {
3         // beginning of docblock template area
4         /**#@+
5          * @access private
6          * @var string 
7          */
8         var $_var1 = 'hello';
9         var $_var2 = 'my';
10        var $_var3 = 'name';
11        var $_var4 = 'is';
12        var $_var5 = 'Bob';
13        var $_var6 = 'and';
14        var $_var7 = 'I';
15        /**
16         * Two words
17         */
18        var $_var8 = 'like strings';
19        /**#@-*/
20        var $publicvar = 'Lookee me!';
21    }

This example will parse as if it were:


1     class Bob
2     {
3         // beginning of docblock template area
4         /**
5          * @access private
6          * @var string 
7          */
8         var $_var1 = 'hello';
9         /**
10         * @access private
11         * @var string 
12         */
13        var $_var2 = 'my';
14        /**
15         * @access private
16         * @var string 
17         */
18        var $_var3 = 'name';
19        /**
20         * @access private
21         * @var string 
22         */
23        var $_var4 = 'is';
24        /**
25         * @access private
26         * @var string 
27         */
28        var $_var5 = 'Bob';
29        /**
30         * @access private
31         * @var string 
32         */
33        var $_var6 = 'and';
34        /**
35         * @access private
36         * @var string 
37         */
38        var $_var7 = 'I';
39        /**
40         * Two words
41         * @access private
42         * @var string 
43         */
44        var $_var8 = 'like strings';
45        var $publicvar = 'Lookee me!';
46    }

Note that for $_var8 the DocBlock template merged with the DocBlock. The rules
for merging are simple:

    *

      The long description of the docblock template is added to the front of
the long description. The short description is ignored.
    *

      All tags are merged from the docblock template