Description

Like the @example tag, the inline example tag can be used to parse an example file for syntax highlighting and linking to documentation. This versatile tag attempts to read the file from the full path specified, and will accept any path that http://www.php.net/fopen will accept. phpDocumentor checks the path to ensure that the file retrieved has a valid .php extension as defined in phpDocumentor.ini, and then opens the file. It will parse the file, and output syntax-highlighted source with line numbers, links to documentation and will then add a link to the documentation to that file.

If given an absolute path, phpDocumentor will not search for the example file any further. If given a relative path (no leading c:\ or /) phpDocumentor searches for examples files first in the directory specified by the -ed, --examplesdir command-line, if present. As of phpDocumentor 1.2.1, it will next search for the file in an examples/ subdirectory of the current file's directory. Otherwise, it will search for a subdirectory named "examples" in the top-level parsing directory, and if not found, in the top-level directory.

The top-level parsing directory is simply the directory that every file parsed has in common.

The inline {@source} tag serves a similar purpose, but instead of parsing a separate file, it parses the current function or method's source.

The {@example} 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, {@example} will print the source code starting on that line number to the end of the function source code. If both parameters are present, {@example} will print an excerpt of the source code beginning on the starting line number, and concluding with the ending line number.

Example

Here's an example:

1. /**
2.  * My function
3.  *
4.  * Here is an inline example:
5.  * <code>
6.  * <?php
7.  * echo strlen('6');
8.  * ?>
9.  * </code>
10.  * and using an external example file:
11.  * {@example /path/to/example.php}
12.  *
13.  * Display only the first 2 lines:
14.  * {@example /path/to/example.php 0 2}
15.  * @example /path/to/example.php How to use this function
16.  * @example anotherexample.inc This example is in the "examples" subdirectory
17.  */
18. function mine()
19. {
20. }