Description

The @see tag may be used to document any element (global variable, include, page, class, function, define, method, variable)

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 http://www.php.net/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:

• :: -- 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.

Example

Here's an example of valid @see syntax:

1. /**
2.  * class 1
3.  * 
4.  * example of use of the :: scope operator
5.  * @see subclass::method()
6.  */
7. class main_class
8. {
9.     /**
10.      * example of linking to same class, outputs <u>main_class::parent_method()</u>
11.      * @see parent_method
12.      */
13.     var foo = 3;
14.  
15.     /**
16.      * subclass inherits this method.
17.      * example of a word which is either a constant or class name, in this case a classname
18.      * @see subclass
19.      * @see subclass::$foo
20.      */
21.  
22.     function parent_method()
23.     {
24.         if ($this->foo==9) die;
25.     }
26. }
27.  
28. /**
29.  * this class extends main_class.
30.  * example of linking to a constant, and of putting more than one element on the same line
31.  * @see main_class, TEST_CONST
32.  */
33. subclass extends main_class
34. {
35.     /**
36.      * example of same class lookup - see will look through parent hierarchy to
37.      * find the method in { @link main_class}
38.      * the above inline link tag will parse as <u>main_class</u>
39.      * @see parent_method()
40.      */
41.     var $foo = 9;
42. }
43.  
44. define("TEST_CONST","foobar");