Question

I’ve installed phpDocumentor 2 and want to include the source for each method in the generated documentation. However, I notice that the inline @source tag does not appear to be picked up, and there only seems to be reference to it in phpDocumentor 1’s documentation.

Here’s what I’ve been trying:

/**
 * Test Comment
 *
 * {@source}
 */
public function test_method() {
    echo('Hi!');
}

I was hoping {@source} would be replaced with the following HTML:

<code>
    echo('Hi!');
</code>

Is this now deprecated? And if so, is there any way to achieve this using phpDocumentor 2?

Answer 1

I’ve had a proper look into this today and spoken with Mike van Riel on the phpDocumentor mailing list.

Simply put – you can’t do exactly what I’m after.

PHPDocumentor 2’s default template, ‘responsive’, has no support for dynamically showing code. What you can do is switch to an alternate template, ‘new-black’, and that will show you the source code for the corresponding file. This works with the @filesource tag and there’s a --sourcecode switch when building the documentation which will automatically enable this for all files.

However, what you can’t do is include code at method level, which is what the @source tag is for. That simply isn’t supported, and the raw structure.xml file doesn’t even store this information.

Having said that, Mike has said “I definitely want the functionality” – so here’s to hoping it gets included in the future! I haven’t got time this second, but I’ll submit it as an issue on GitHub. If you’re keen on having this functionality too, please make it known.