Previous Up Next
inline {@link} phpDocumentor Inline tags inline {@toc}

inline {@source}

Display source code of a function or method in the long description

Gregory Beaver
Tag Documentation written by [email protected]
Copyright 2002, Gregory Beaver
(phpDocumentor 1.1+ (undocumented in 1.1))
{@source startline number of lines }

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.  */

Previous Up Next
inline {@link} phpDocumentor Inline tags inline {@toc}

Documentation generated on Mon, 05 Dec 2011 21:13:07 -0600 by phpDocumentor 1.4.4