returntypewillchange.xml Add warning about future strict return type …#5608
returntypewillchange.xml Add warning about future strict return type …#5608mmalferov wants to merge 12 commits into
Conversation
…enforcement Should we not explicitly mention that internal methods will strictly enforce return types in future PHP versions? Currently, the documentation might give developers a false sense of security, making it look like `#[ReturnTypeWillChange]` is a permanent fix. In reality, it only works during the tentative phase. Once PHP 9.0 drops, any remaining signature mismatches in child classes will cause a fatal error, as far as I understand
| deprecation warnings during the tentative return type phase <emphasis>only</emphasis>. | ||
| Any remaining signatures mismatches will trigger an <constant>E_COMPILE_ERROR</constant> once internal methods | ||
| transition to standard strict return types. This breaking change is scheduled for PHP 9.0.0, | ||
| at which point a fatal error is raised and this attribute will no longer have any effect. |
There was a problem hiding this comment.
We generally avoid mentioning planned future release behaviour in the docs, since release plans can change and the information tends to become outdated quickly.
I think it would be enough to state it only suppresses deprecation notices during the tentative return type phase.
There was a problem hiding this comment.
I completely agree that mentioning specific versions and error constants was overkill. I've removed them to keep the focus purely on the core behavior.
The term tentative return type was used in the warning without being defined anywhere else in the text, which could be confusing. So I briefly defined what the tentative phase actually means.
Thank you for the guidance! Ready for another look
jordikroon
left a comment
jordikroon
left a comment
There was a problem hiding this comment.
Since we touch <para> it should become <simpara>. Could you do a rebase with master as well, so that checks will run correctly.
Co-authored-by: Jordi Kroon <jordi@jordikroon.nl>
Co-authored-by: Jordi Kroon <jordi@jordikroon.nl>
…etqos_class (php#5609) * Fix duplicate documentation for pcntl_getqos_class and pcntl_setqos_class These functions were each documented in two files sharing the same xml:id. The build normalizes _ to - in file-entity names, so the hyphen-named files (php#5350) collided with the underscore-named ones (php#5506) and were silently dropped. Merge both versions into the hyphen-named files and remove the underscore-named ones. * Address review: use exceptionname for Error and simpara for parameters Mark the thrown Error with <exceptionname>, use <simpara> for the qos_class description, and drop the <para> wrapper around its <variablelist>.
3 participants
…enforcement
Should we not explicitly mention that internal methods will strictly enforce return types in future PHP versions?
Currently, the documentation might give developers a false sense of security, making it look like
#[ReturnTypeWillChange]is a permanent fix. In reality, it only works during the tentative phase. Once PHP 9.0 drops, any remaining signature mismatches in child classes will cause a fatal error, as far as I understand