|  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #76060 ReflectionProperty::getDocComment() can return false
Submitted: 2018-03-06 12:05 UTC Modified: 2018-03-07 05:00 UTC
From: benjamin dot morel at gmail dot com Assigned:
Status: Open Package: Reflection related
PHP Version: Irrelevant OS: N/A
Private report: No CVE-ID: None
Have you experienced this issue?
Rate the importance of this bug to you:

 [2018-03-06 12:05 UTC] benjamin dot morel at gmail dot com
The manual pages for getDocComment() methods state that they return string:

However, they can all return false when there is no doc comment:


class Foo {
    public const BAR = '';

    public $bar;

    public function bar() {}

var_export((new ReflectionClass('Foo'))->getDocComment());                // false
var_export((new ReflectionClassConstant('Foo', 'BAR'))->getDocComment()); // false
var_export((new ReflectionMethod('Foo', 'bar'))->getDocComment());        // false
var_export((new ReflectionProperty('Foo', 'bar'))->getDocComment());      // false

Expected result:
public string|bool ReflectionClass::getDocComment ( void )
public string|bool ReflectionClassConstant::getDocComment ( void )
public string|bool ReflectionFunctionAbstract::getDocComment ( void )
public string|bool ReflectionProperty::getDocComment ( void )

Actual result:
public string ReflectionClass::getDocComment ( void )
public string ReflectionClassConstant::getDocComment ( void )
public string ReflectionFunctionAbstract::getDocComment ( void )
public string ReflectionProperty::getDocComment ( void )


Add a Patch

Pull Requests

Add a Pull Request


AllCommentsChangesGit/SVN commitsRelated reports
 [2018-03-06 12:16 UTC]
-Status: Open +Status: Suspended
 [2018-03-06 12:16 UTC]
The prototype says string. The docs say it can return false.

Many functions are like this. Talk to the phpdoc mailing list to see what they think about it.
 [2018-03-06 12:29 UTC] benjamin dot morel at gmail dot com
I will.
In the meantime, while the first 3 say that it can return FALSE, the last one does not:

"Return Values
The property doc comment."

At least this one should be fixed right now.
 [2018-03-06 12:31 UTC]
-Summary: getDocComment() can return false +Summary: ReflectionProperty::getDocComment() can return false -Status: Suspended +Status: Open
 [2018-03-06 15:31 UTC]
This issue already came up on the docs mailing list:
 [2018-03-06 15:54 UTC] benjamin dot morel at gmail dot com
Thanks for the pointer! There was no consensus as far as I can tell. But I personally fully agree with Richard Quadling:

> The inability of the function/method signature correctly express itself is
a pain. You read the signature. It says "I return stuff". I then have to
read the rest of the documentation to find that it returns something useful
or false.

> int|false (as true and false are now types), is
very explicit, understandable, parseable and can be used by other systems
in a concise way.
 [2018-03-06 17:05 UTC]
>> int|false (as true and false are now types), is very
>> explicit, understandable, parseable and can be used by other
>> systems in a concise way.

And it is usually wrong as well, see <>,
for instance.
 [2018-03-06 17:40 UTC] benjamin dot morel at gmail dot com
Did you send the correct link? I'm not sure what you mean here.
 [2018-03-07 05:00 UTC]
I think the meaning is it can return other values too, like NULL, or return no value at all. In that case string|bool is not fully accurate.

This is why this idea runs into a brick wall and dies every few years or so.

Now, is string|bool more useful than string? Probably. Or should it be explicit and include all possible return types like let's say string|bool|null|void or somesuch. Maybe. Or simply be "mixed" like some are today? Probably not.

Good times :)
PHP Copyright © 2001-2021 The PHP Group
All rights reserved.
Last updated: Fri May 14 08:01:23 2021 UTC