@example

Description

The 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 @filesource tag serves a similar purpose, but instead of parsing a separate file, it parses the current file's source.

To do an inline code example, use the html tag <code> or the new inline {@example} tag

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.  * @example /path/to/example.php How to use this function
11.  * @example anotherexample.inc This example is in the "examples" subdirectory
12.  */
13. function mine()
14. {
15. }