@see

(phpDocumentor 0.1+ )

@see --  display a link to the documentation for an element

Description

@see file.ext|elementname|class::methodname()|class::$variablename|functionname()|function functionname

You may use the @see tag to document any element (global variable, include, page, class, function, define, method, variable)

Caution

@see only displays links to element documentation. If you want to display a hyperlink, use @link or inline {@link}

New in version 1.2: You can link to any defined function in the current php version using the function's name. This linking is done using the standard php function get_defined_functions, and so relies on the version of php that is used to execute phpDocumentor. A benefit of this method is that the function highlighting will automatically upgrade with a php upgrade without any change to the underlying code. You may also link directly to any portion of the php website using the fake package override PHP_MANUAL (as in PHP_MANUAL#get_defined_functions, or PHP_MANUAL#support.php)

Along with inline {@link}, the @see tag is among the most useful features of phpDocumentor. With this tag, you can create a link to any element (except include/require) in the documentation with a very wide range of options. The @see parser can be told exactly where to look using some basic punctuation:

However, @see is also intelligent enough to recognize shorthand. If @see receives an elementname with no punctuation, it will search for an element in this order:

  1. is elementname the name of a class?
  2. is elementname the name of a procedural page? (file.ext)
  3. is elementname the name of a define?
  4. if the DocBlock containing the @see is in a class:
    1. is elementname a method?
    2. is elementname a variable?
  5. is elementname a function?

@see parsing is slightly slower when passed an elementname with no punctuation, especially if the elementname is a function, so use it sparingly in large projects (500+ elements with @sees in their DocBlocks). The best use for punctuation-less elementname is in a project whose classnames are in flux.

Here's an example of valid @see syntax:

/**
* class 1
* 
* example of use of the :: scope operator
* @see subclass::method()
*/
class main_class
{
	/**
	* example of linking to same class, outputs "function main_class::parent_method()
	* @see function parent_method
	*/
	$var foo = 3;

	/**
	* subclass inherits this method.
	* example of a word which is either a constant or class name, in this case a classname
	* @see subclass
	* @see subclass::$foo
	*/

	function parent_method()
	{
		if ($this->foo==9) die;
	}
}

/**
* this class extends main_class.
* example of linking to a constant, and of putting more than one element on the same line
* @see main_class, TEST_CONST
*/
subclass extends main_class
{
	/**
	* bar.
	* example of same class lookup - see will look through parent hierarchy to find the method in {@link main_class}
	* the above inline link tag will parse as main_class
	* @see parent_method()
	*/
	var $foo = 9;
}

define("TEST_CONST","foobar");