Doc #79484 [Opn]: Declared full covariance and contravariance support should be refined

Edit report at https://bugs.php.net/bug.php?id=79484&edit=1 ID: 79484 Updated by: cmb@php.net Reported by: vlad dot turchinskiy at yandex dot ru Summary: Declared full covariance and contravariance support should be refined Status: Open Type: Documentation Problem Package: PHP Language Specification Operating System: any PHP Version: 7.4.5 Block user comment: N Private report: N New Comment: The PHP manual is already clear about that[1]: | Covariance allows a child's method to return a more specific | type than the return type of its parent's method. Whereas, | contravariance allows a parameter type to be less specific in a | child method, than that of its parent. It appears, though, that the language specification is not[2]. [1] <https://www.php.net/manual/en/language.oop5.variance.php> [2] <https://github.com/php/php-langspec/tree/master/spec> Previous Comments: ------------------------------------------------------------------------ [2020-04-17 08:21:16] vlad dot turchinskiy at yandex dot ru Description: ------------ On the doc page https://www.php.net/manual/en/language.oop5.variance.php declared that "As of PHP 7.4.0, full covariance and contravariance support was added". As mentioned by derick@php.net at #79482 (https://bugs.php.net/bug.php?id=79482): "Function arguments are contra-variant, not co-variant, meaning that an overloaded/inherited method can chose to accept a broader type. If it would allow for a more specific/narrow type, then an already existing bit of code could no longer call the overloaded with the same method arguments as the original parent class." This should be refined in docs. In the current state, docs goes against POLA (https://en.wikipedia.org/wiki/Principle_of_least_astonishment). Provided test script to demonstrate. Test script: --------------- https://3v4l.org/vC0WM Expected result: ---------------- The fact that "Function arguments are contra-variant, not co-variant" should be mentioned at https://www.php.net/manual/en/language.oop5.variance.php Better, if it had an example. Actual result: -------------- Declared full covariance and contravariance support ------------------------------------------------------------------------ -- Edit this bug report at https://bugs.php.net/bug.php?id=79484&edit=1