I can not seem to understand how to get PHPCocumentor2 @example tags to work correctly.
I am attempting to parse a single file. My working directory is /home/developers/domains/example.com and I am trying to parse (relative to my working directory) simplesamlphp/modules/example/lib/Auth/Process/RoleTrigger.php. This class file has a DocBloc that looks like:
/**
* Trigger Role on User from Configuration.
*
* @example "RoleManager.usage.example.php" Test Example
*/
public function process() { /* ... */ }
When I run the command to parse just this file in maximum verbosity (phpdoc -f simplesamlphp/modules/example/lib/Auth/Process/RoleTrigger.php -t httpdocs/test -vvv) PhpDoc indicates that the current project root is /home/developers/domains/example.com/simplesamlphp/modules/example/lib/Auth/Process/, so, according to the Documentation, this indicates that the example file RoleManager.usage.example.php should be located either at the same directory level of the parsed file, or in the examples directory of the current Project Root (which would be /home/developers/domains/example.com/simplesamlphp/modules/example/lib/Auth/Process/examples/).
However, try as I might, I can not seem to get the Example to show up in the generated documentation.
All I seem to get is, on the right-hand side of the generated page:
Tags
example Test Example
With no hyper-link, or display of the file contents, or anything. Just the "Description" with nothing else.
I have attempted to use <code> but multiple lines with multiple levels render broken html that is also useless:
This:
/**
* Test Doc
*
* <code>
* <?php
* $array = array(
* 1 => 'one',
* 2 => 'two',
* );
* print_r($array);
* ?>
* </code>
*/
Renders the following HTML:
<p><code>
<?php
$array = array(</p>
<pre><code>1 => 'one',
2 => 'two',</code></pre>
<p>);
print_r($array);
?>
</code></p>
Multiple nested <code> and <pre> tags that render something awful. But that is a different issue.
When I initially posted this question, it happens that the @example tag was not implemented (yet) in PHPDocumentor v2. This is an unfortunate truth for a number of tags as PHPDocumentor v2 is built on top of a completely different foundation than v1, and tags were/are still being ported to the new system.
Shortly after I posted the question I checked in with the Git community working on the project and contributed a little to the task of implementing the @example tag.
At this time, the tag works as expected and defined in the PHPDoc documentation, to the T (so far as I can test).
http://www.phpdoc.org/docs/latest/references/phpdoc/tags/example.html
It does occur to me that, as this now works as expected, this question (and answer) are likely no longer needed. However I wanted to make sure that I updated it lest someone stumble upon it and become confused.
For completeness sake, at the time of writing, the syntax executes as follows:
/**
* @example [location] [<start-line> [<number-of-lines>] ] [<description>]
*/
/**
* Or inline {@example [location] [<start-line> [<number-of-lines>] ] [<description>]}
*/