According to PHPDocumentor's documentation, to show an example it would be like this:
@example [location] [<start-line> [<number-of-lines>] ] [<description>]
This seems like a valid solution if code never changes but whenever you go and add new code to wherever the location is, your start-line potentially changes meaning you have to constantly be updating these various references.
Is there a better way to show an example of how to use a class method, within the DocBlock, without referencing an external current use example?
Here is what I am aiming for:
/**
* @example This is how you use this method:
*
* $baz = Foo::bar( array('bing' => $bing) );
*/
And then it shows up in the documentation as an example. Any ideas?
You can show a code example in the docblock itself by means of the "code" delimiter. So, for your original example:
/**
* This is how you use this method:
* <code>
* $baz = Foo::bar( array('bing' => $bing) );
* </code>
*/
The manual page [1] for the @example tag shows both a "code" section in the docblock as well as @example pointers to lines in separate files.
[1] -- http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.example.pkg.html