Prev Next

@example

Include an external example file with syntax highlighting

by Gregory Beaver
Tag Documentation written by [email protected]
Copyright 2002, Gregory Beaver
(phpDocumentor 1.2+)
@example /path/to/example.php description
(phpDocumentor 1.2.1+) @example url://path/to/example.php description
@example relativepath/to/example.php description

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 only works with PHP 4.3.0+ due to the use of the tokenizer extension, which was not stable prior to PHP 4.3.0. Go to http://www.php.net and download PHP 4.3.0 to use @example

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. }

Prev Up Next
@deprecated phpDocumentor tags @final

Documentation generated on Mon, 05 Dec 2011 21:24:12 -0600 by phpDocumentor 1.4.4