The first parameter to @version tag is ignored, and version field is blank in the output

[susam]

I am using phpdoc 2.0.1 on Debian Testing version (Jessie).

$ phpdoc --version 2> /dev/null
phpDocumentor version 2.0.1

Here is a test script foo.php to reproduce the issue:

<?php
/**
 * Foo script
 *
 * This script contains a class called Foo.
 *
 * @author Humpty Dumpty
 * @copyright 2013 Humpty Dumpty
 * @license http://creativecommons.org/publicdomain/zero/1.0/ Public domain
 * @version 0.1
 */

/**
 * Foo class
 *
 * This class contains a method called foo.
 *
 * @author Humpty Dumpty
 * @copyright 2013 Humpty Dumpty
 * @license http://creativecommons.org/publicdomain/zero/1.0/ Public domain
 * @version 0.1
 */
class Foo
{
    /**
     * Prints foo
     *
     * @return void
     */
    public function foo()
    {
        echo "foo\n";
    }
}
?>

After executing phpdoc -d . -t docs to generate the
documentation, this is what I see:

You can see that the 'Version' field appears to be blank.

However if I change the @version tag from

@version 0.1

to

@version 0.1 Unstable

then I see the following output:

It looks like only the second parameter to @version tag is
displayed in the output. From the documentation at
http://www.phpdoc.org/docs/latest/for-users/phpdoc/tags/version.html
it looks like, @version 0.1 should also work, i.e. the first
parameter to @version tag should also be displayed in the
output.

This issue occurs for @since tag too.

[susam]

Until this issue is resolved, I am using @version tag in the following manner:

@version v0.1

As long as the first parameter (vector) to @version doesn't begin with a digit, it appears in the output. Another such workaround is:

@version Version 0.1

The following works too.

@version GIT: 0.1

The above usage seems like the intended usage of this tag as is evident from the code examples in the following URLs:

1. http://www.phpdoc.org/docs/latest/for-users/phpdoc/tags/version.html#examples (See docblock for class NeoCounter)
2. http://pear.php.net/manual/en/standards.sample.php (See docblock for the file and class Net_Sample)
3. http://framework.zend.com/manual/1.12/en/coding-standard.coding-style.html#coding-standards.inline-documentation.classes

For @since tag, I am using the following workarounds.

The following works fine in a docblock for a file.

@since File 0.1 Added class Foo

The following works fine in a docblock for a class.

@since Class 0.1 Added method foo

The above two examples of @since tag indeed seems like the intended usage as can be seen in the first two URLs I have provided above. Of course, the following would work too since the first parameter to @since doesn't begin with a digit.

@since version 0.1 Added cool blue buttons

[boenrobot]

Note that the only reason this workaround works is because "GIT: 0.1" is not actually a valid "GIT" version vector, and is therefore treated as part of a plain text description. The version vector is supposed to be enclosed within "$" (see first and second example you gave).

[mvriel]

This item should be verified before version 2.4 is released to see if all mentioned issues are resolved

[toxalot]

@mvriel This is not resolved in 2.4. @boenrobot Is the version number always supposed to be enclosed within $? As I read the docs the vector MUST follow a certain form only for vectors from Version Control Systems. However, judging by the example given on that documentation page, a plain number should work also.

[boenrobot]

The two forms shown in the docs are the two supported ones - a number without any sort of prefix, and a VCS vector enclosed with "$".

As I noted above, the reason you are seeing the version (whether it's when you prefix it with "v" or not enclose a VCS vector in "$") is because THOSE forms are considered invalid. Thus, phpDocumentor treats them as plain text descriptions, which are shown without a problem.

phpDocumentor should display recognized version vectors alongside the description (perhaps bolded or whatever), but apparently, it's still not doing that.

[jwleon]

Are we going to see this? It seems like it is still not working correctly...

[jaapio]

@TheCodePianist can you confirm this issue is solved with the version that is currently available in master? I think it is solved.

[ve3]

I'm using phpDocumentor 2.9.0 but this document @version 1.0 is still not working. It is not solved at all.

[jaapio]

@ve3 can you tell me in which situation @Version 1.0 doesn't work for you? Do you have a public example? Which template are you using?

[ve3]

@jaapio #1843

[mvriel]

I doublechecked whether this issue still exists in the latest version using the default template and it seems to be fine now:

As such, I am closing this issue as resolved