@see

Description

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

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:

• ::  --  This is the class scope override. Use it to tell the @see parser which class to look in for the element specified,
  like classname::methodname() or classname::$variablename.
• ()  --  When present at the end of elementname, like elementname(), this tells the @see parser to search for a function or method.
• $  --  When present at the beginning of elementname, like $elementname, this tells the @see parser to search for a variable in the current class.

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");