Previous | Up | Next |
@return | phpDocumentor tags | @since |
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:
is elementname the name of a class?
is elementname the name of a procedural page? (file.ext)
is elementname the name of a define?
if the DocBlock containing the @see is in a class:
is elementname a method?
is elementname a variable?
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:
Previous | Up | Next |
@return | phpDocumentor tags | @since |
Documentation generated on Mon, 05 Dec 2011 21:18:39 -0600 by phpDocumentor 1.4.4