Phpdocumentor: Documentation or bug ? Handling of <code> tags in long descriptions

Created on 15 Jun 2020 · 3Comments · Source: phpDocumentor/phpDocumentor

In phpDocumentor 1, <code> tags could be used to generate a code block. This was definitely supported in long descriptions. I'm not sure if it was supported elsewhere.

I'm not sure whether this was supported in phpDocumentor 2, but it definitely isn't supported in 3.

Support being dropped, in itself, is not a problem as the markdown "_triple backtick, optionally with language_" syntax can be used instead.

However, I couldn't find anything about when support for this was dropped in the documentation and/or changelog, nor in an upgrade guide,

So that makes me wonder if dropping support was an oversight (unintentional), in which case, this is a bug report.

If the dropping of the support _was_ intentional, or if it would be decided based on this issue that it is retroactively no longer supported, I'd like to suggest adding a changelog entry to the phpDocumentor version in which this was dropped and to make sure it is included in an end-user upgrade guide.

I can also imagine that any instances of <code> found in the docs could be listed in the "Deprecated" or "Error" report to make it easier for end-user devs to update their docs to use the triple backtick.

Expected behavior

That use of <code> would either still be supported or would generate a warning/error and that the dropping it would be mentioned somewhere.

Code sample:

    /**
     * Retrieve information.
     *
     * The return value is in the following format:
     *
     * <code>
     * 0 => array(
     *   'name'  => '$var',  // The variable name.
     *   'token' => integer, // The stack pointer to the variable name.
     * )
     * </code>
     *
     * @return array
     */
    function foo() {}

Actual behavior

Both the <code> tags, as well as the text between them, is treated like ordinary text and no deprecations/errors/markers are shown in the reports.

issue-2430

Steps to reproduce the problem

Issue can be reproduced with the above code sample.
Run php -f /path/to/phpDocumentor/bin/phpdoc

Your environment

Version used: phpDocumentor v3.0.x-dev@d15f2d6
Install method: git clone
PHP version: 7.4.6
Operating system and version: Windows 7

bug

Source

jrfnl

All 3 comments

Just found issue #685. Based on that the <code> tag was supported in phpDocumentor 2.

jrfnl on 16 Jun 2020

I don't remember what happened to this. I am not opposed to reintroducing this. As this is a code change, I will have to defer working on this until I am done with the template changes