Description

The {@source} inline tag is used in the DocBlock of functions or methods to extract source code of the function/method for display in generated documentation. This tag is designed to allow detailed line-by-line description of how a function works without having to cut and paste from the source. This allows modification to the source and automatic update of documentation so that it remains current.

Example

The inline {@source} differs from all ordinary tags. Inline tags parse and display their output directly in the documentation. In other words, this DocBlock:

1. /**
2.  * Text with a normal tag, @copyright
3.  * @copyright Copyright 2002, Greg Beaver
4.  */
5. function element()
6. {
7. }

will display normal documentation.

This DocBlock:

1. /**
2.  * Text with an inline source tag:
3.  *
4.  * {@source } 
5.  * displays without a break in the flow
6.  */
7. function element($pages)
8. {
9.     if (empty($pages))
10.     {
11.         die("<b>ERROR</b>: nothing parsed");
12.     }
13. }

will display the complete source inside the documentation as if we had typed it out

1. /**
2.  * Text with an inline source tag:
3.  *
4.  * <code>
5.  * function element($pages)
6.  * {
7.  *     if (empty($pages))
8.  *     {
9.  *         die("<b>ERROR</b>: nothing parsed");
10.  *     }
11.  * }
12.  * </code>
13.  * displays without a break in the flow
14.  */

The {@source tag has two optional parameters, the starting line number to display and the ending line number to display. If only the first parameter is present, {@source} will print the source code starting on that line number to the end of the function source code. If both parameters are present, {@source} will print an excerpt of the source code beginning on the starting line number, and concluding with the ending line number.

1. /**
2.  * Text with an inline source tag:
3.  *
4.  * {@source 3}
5.  * displays without a break in the flow
6.  */
7. function element($pages)
8. {
9.     if (empty($pages))
10.     {
11.         die("<b>ERROR</b>: nothing parsed");
12.     }
13.     foreach($test as $hello)
14.     {
15.         echo "I love $hello";
16.     }
17. }

Parses as if we had coded:

1. /**
2.  * Text with an inline source tag:
3.  *
4.  * <code>
5.  *     if (empty($pages))
6.  *     {
7.  *         die("<b>ERROR</b>: nothing parsed");
8.  *     }
9.  *     foreach($test as $hello)
10.  *     {
11.  *         echo "I love $hello";
12.  *     }
13.  * }
14.  * </code>
15.  * displays without a break in the flow
16.  */

1. /**
2.  * Text with an inline source tag:
3.  * {@source 3 1}
4.  * displays without a break in the flow
5.  */
6. function element($pages)
7. {
8.     if (empty($pages))
9.     {
10.         die("<b>ERROR</b>: nothing parsed");
11.     }
12.     foreach($test as $hello)
13.     {
14.         echo "I love $hello";
15.     }
16. }

Parses as if we had coded:

1. /**
2.  * Text with an inline source tag:
3.  *
4.  * <code>
5.  *     if (empty($pages))
6.  * </code>
7.  * displays without a break in the flow
8.  */