Previous Up Next
@return phpDocumentor tags @since

@see

Display a link to the documentation for an element

Gregory Beaver
Tag Documentation written by [email protected]
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

Description

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

Previous Up Next
@return phpDocumentor tags @since

Documentation generated on Mon, 05 Dec 2011 21:29:50 -0600 by phpDocumentor 1.4.4