Doc #76060 [Opn]: ReflectionProperty::getDocComment() can return false

Edit report at https://bugs.php.net/bug.php?id=76060&edit=1 ID: 76060 Updated by: cmb@php.net Reported by: benjamin dot morel at gmail dot com Summary: ReflectionProperty::getDocComment() can return false Status: Open Type: Documentation Problem Package: Reflection related Operating System: N/A PHP Version: Irrelevant Block user comment: N Private report: N New Comment: >> 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. Previous Comments: ------------------------------------------------------------------------ [2018-03-06 15:54:44] 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 15:31:47] 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 12:29:38] 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:16:54] 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:05:58] 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 ) ------------------------------------------------------------------------ -- Edit this bug report at https://bugs.php.net/bug.php?id=76060&edit=1