php.net |  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: 2021-05-22 13:15 UTC
From: benjamin dot morel at gmail dot com Assigned: krakjoe (profile)
Status: Closed Package: Reflection related
PHP Version: Irrelevant OS: N/A
Private report: No CVE-ID: None
View Add Comment Developer Edit
Welcome! If you don't have a Git account, you can't do anything here.
You can add a comment by following this link or if you reported this bug, you can edit this bug over here.
(description)
Block user comment
Status: Assign to:
Package:
Bug Type:
Summary:
From: benjamin dot morel at gmail dot com
New email:
PHP Version: OS:

 

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

http://php.net/manual/en/reflectionclass.getdoccomment.php
http://php.net/manual/en/reflectionclassconstant.getdoccomment.php
http://php.net/manual/en/reflectionfunctionabstract.getdoccomment.php
http://php.net/manual/en/reflectionproperty.getdoccomment.php

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

<?php

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 )

Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2018-03-06 12:16 UTC] requinix@php.net
-Status: Open +Status: Suspended
 [2018-03-06 12:16 UTC] requinix@php.net
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:
http://php.net/manual/en/reflectionproperty.getdoccomment.php

"Return Values
The property doc comment."

At least this one should be fixed right now.
 [2018-03-06 12:31 UTC] requinix@php.net
-Summary: getDocComment() can return false +Summary: ReflectionProperty::getDocComment() can return false -Status: Suspended +Status: Open
 [2018-03-06 15:31 UTC] cmb@php.net
This issue already came up on the docs mailing list:
<https://marc.info/?t=151246911600002&r=1&w=2>.
 [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] cmb@php.net
>> 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 <https://3v4l.org/D2Tm3>,
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] philip@php.net
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 :)
 [2021-05-22 13:15 UTC] krakjoe@php.net
-Status: Open +Status: Closed -Assigned To: +Assigned To: krakjoe
 [2021-05-22 13:15 UTC] krakjoe@php.net
The documentation has been fixed.
 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved.
Last updated: Tue Mar 19 06:01:30 2024 UTC