phpDocumentor bug

[jim-parry]

phpDocumentor2 does not properly recognize the hinted return type in PHP7.
In order to generate phpdocs for CI4, the return types in method signatures have been commented out for now. They can be restored using a global search & replace once phpDocumentor has addressed their issue.

Desired: function banana(): fruit
Workaround: function banana()//: fruit

Or, for an interface...
Desired: function banana(): fruit;
Workaround: function banana();//: fruit;

[sv3tli0]

Braking PHP features, just to have auto generating documentation doesn't sounds good..

If phpDocumentor is not PHP 7 ready the best thing is not to use it.
CI 4 is based on PHP 7 so anything used by the framework must be compatible with 7 on 100%.

[jim-parry]

@sv3tli0
phpDocumentor is almost ready for PHP7 ... that might end up being phpDocumentor3 - unclear.

What I have done doesn't break anything, it just doesn't exploit the return type hinting in PHP7. The code is eminently functional as is, and the PHPdocs will be accurate.

We made a conscious decision to use phpdoc to generate the API documentation, because it is so onerous to include it in the user guide. phpDocumentor is the best (only?) tool I have found for that.

[sv3tli0]

The idea is fine but until this next version which supports PHP 7 is out this should be waiting to be added.
CI is an example of almost ready version which had years delay..

[jim-parry]

@sv3tli0 I agree it could be a long time before phpDocumentor is "complete".
How would you then suggest we generate API documentation?
I have tried all of the tools I could find to do so, and phpDocumentor was the best of them.
If we leave the return type hinting in the code, any class or interface which uses the feature gets excluded from the API docs.

[jim-parry]

phpDocumentor v2.9.0 has fixed the problem :)
The return type hinting will be restored!

[sv3tli0]

True.. I read about this new version earlier today but I haven't tested it to comment it.