[ class tree: phpDocumentor ] [ index: phpDocumentor ] [ all elements ]
Prev Next


Display a link to the documentation for an element

by Gregory Beaver
Tag Documentation written by
Copyright 2002, Gregory Beaver
(phpDocumentor 0.1+)
@see file.ext|elementname|class::methodname()|class::$variablename|functionname()|function functionname unlimited number of values separated by commas


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

@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, 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.


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;
  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.      */
  22.     function parent_method()
  23.     {
  24.         if ($this->foo==9die;
  25.     }
  26. }
  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. }
  44. define("TEST_CONST","foobar");

Prev Up Next
@return phpDocumentor tags @since

Documentation generated on Sun, 02 Sep 2012 00:00:38 +0000 by phpDocumentor 1.4.3. PEAR Logo Copyright © PHP Group 2004.