php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login

go to bug id or search bugs for

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
View Add Comment Developer Edit
Welcome back! If you're the original bug submitter, here's where you can edit the bug or add additional notes.
If this is not your bug, you can add a comment by following this link.
If this is your bug, but you forgot your password, you can retrieve your password here.
Password:
Status:
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 :)
 
PHP Copyright © 2001-2020 The PHP Group
All rights reserved. 		Last updated: Wed Oct 21 18:01:24 2020 UTC