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
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:
/**
* Text with a normal tag, @copyright
* @copyright Copyright 2002, Greg Beaver
*/
function element()
{
}
will display normal documentation.
This DocBlock:
/**
* Text with an inline source tag:
*
* {@source }
* displays without a break in the flow
*/
function element($pages)
{
if (empty($pages))
{
die("<b>ERROR</b>: nothing parsed");
}
}
will display the complete source inside the documentation as if we had typed it out
/**
* Text with an inline source tag:
*
* <code>
* function element($pages)
* {
* if (empty($pages))
* {
* die("<b>ERROR</b>: nothing parsed");
* }
* }
* </code>
* displays without a break in the flow
*/
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.
/**
* Text with an inline source tag:
*
* {@source 3}
* displays without a break in the flow
*/
function element($pages)
{
if (empty($pages))
{
die("<b>ERROR</b>: nothing parsed");
}
foreach($test as $hello)
{
echo "I love $hello";
}
}
Parses as if we had coded:
/**
* Text with an inline source tag:
*
* <code>
* if (empty($pages))
* {
* die("<b>ERROR</b>: nothing parsed");
* }
* foreach($test as $hello)
* {
* echo "I love $hello";
* }
* }
* </code>
* displays without a break in the flow
*/
/**
* Text with an inline source tag:
* {@source 3 1}
* displays without a break in the flow
*/
function element($pages)
{
if (empty($pages))
{
die("<b>ERROR</b>: nothing parsed");
}
foreach($test as $hello)
{
echo "I love $hello";
}
}
Parses as if we had coded:
/**
* Text with an inline source tag:
*
* <code>
* if (empty($pages))
* </code>
* displays without a break in the flow
*/
Previous
|
Up
|
Next
|
inline {@link}
|
phpDocumentor Inline tags
|
inline {@toc}
|
Documentation generated on Mon, 05 Dec 2011 21:18:42 -0600 by phpDocumentor 1.4.4