CHAPTER 16 ■ GENERATING DOCUMENTATION WITH PHPDOCUMENTOR
Notice, though, that we also embedded a reference to Command::execute() in the DocBlock
description text. We can transform this into a live link by using the @link tag. @link can be added at the
beginning of a line, as @see is, but it can also be used inline. In order to differentiate inline tags from their
surroundings, you must surround them with curly brackets. So, to make my embedded reference to
Command::execute() clickable, I would use the following syntax:
// ...
- Commands require disparate data according to context. The
- CommandContext object is passed to the {@link Command::execute()}
- method and contains data in key/value format. The class
//...
Because the @link tag in the previous fragment includes only the element reference
(Command::execute()), it is this string that becomes clickable. If I were to add some description here, it
would become clickable instead.
@link can be used to refer to URLs as well. Simply replace the element reference with a URL:
@link http://www.example.com More info
Once again, the URL is the target, and the description that follows it is the clickable text.
You may want to make a reciprocal link. Command uses CommandContext objects, so I can create a link
from Command::execute() to the CommandContext class and a reciprocal link in the opposite direction. I
could, of course, do this with two @link or @see tags. @uses handles it all with a single tag, however:
/**
- Perform the key operation encapsulated by the class.
- ...
- @param $context {@link CommandContext} Shared contextual data
- @return bool false on failure, true on success
- @link http://www.example.com More info
- @uses CommandContext
*/
abstract function execute( CommandContext $context );
In adding the @uses tag, I create a link in the Command::execute() documentation: “Uses:
CommandContext”. In the CommandContext class documentation, a new link will appear: “Used by:
Command::execute()”.
You can see the latest output in Figure 16–8. Note that I have not used @link inline, so it is output in
list format.