Generate deprecation warning box for the manual #14938
Conversation
| $refsynopsisDiv = $doc->createElement('refsynopsisdiv'); | ||
| $deprecationEntity = $doc->createEntityReference( | ||
| 'warn.deprecated.' . (isset($aliasMap[$this->name->__toString()]) ? 'alias' : 'function-') . | ||
| str_replace(".", "-", $this->deprecatedSince) . "-0" |
There was a problem hiding this comment.
@TimWolla The since property currently doesn't contain the patch version. However, theoretically it's possible to deprecate symbols in patch versions as well... So I'm wondering whether the .0 suffix could be added to the property value?
There was a problem hiding this comment.
Also, currently, 3rd party extensions shouldn't really use Deprecated attributes... because currently I have to assume that the value of the since property relates to PHP versions, and not the version of the extension itself.
There was a problem hiding this comment.
However, theoretically it's possible to deprecate symbols in patch versions as well... So I'm wondering whether the .0 suffix could be added to the property value?
I don't see a value-add in that. Deprecations in patch version should be very rare. As an example, if folks convert deprecations to Exceptions this would cause a break. Yes, folks should not do that, but they do.
Pretending that the deprecation was there in the .0 version is a good enough approximation, because only the latest patch version of a branch is supported anyways.
There was a problem hiding this comment.
Also, currently, 3rd party extensions shouldn't really use
Deprecatedattributes... because currently I have to assume that the value of thesinceproperty relates to PHP versions, and not the version of the extension itself.
| if ($funcInfo->deprecatedSince) { | ||
| foreach ($doc->getElementsByTagName("refentry") as $refentryElement) { | ||
| foreach ($refentryElement->getElementsByTagName("refnamediv") as $refnameDivElement) { | ||
| if (count($refnameDivElement->getElementsByTagName("refname")) !== 1) { |
There was a problem hiding this comment.
The warning saying This function has been DEPRECATED as of ... doesn't make sense on pages where multiple functions/methods are documented, so I skip the automatic addition of the box in such cases.
| 'warn.deprecated.' . (isset($aliasMap[$this->name->__toString()]) ? 'alias' : 'function-') . | ||
| str_replace(".", "-", $this->deprecatedSince) . "-0" | ||
| ); | ||
| $refsynopsisDiv->appendChild(new DOMText("\n ")); |
There was a problem hiding this comment.
You can actually simplify DOMText insertions as follows:
| $refsynopsisDiv->appendChild(new DOMText("\n ")); | |
| $refsynopsisDiv->append("\n "); |
or even combine the 3 appendChilds into one, but I guess you didn't do it because it would be a long line or would have to be multilined anyway.
|
I am wondering if we shouldn't move this to PhD, as in use the information of the This information is already used to generate the ToC and move deprecated functions/methods into a new box: This would lower the maintenance burden for translations, and have the information be more accurate from the get go, changelogs would still need to be manually added however |
|
Although for this to work, we would need gen_stub to properly generate the |
Yes, and there's another problem with the alternative suggestion: this information isn't available for phd. And as I found out, not even gen_stub.php can always generate this properly. :( On one hand, it's because the XML markup is missing when a symbol is referenced (e.g.: That's why I went with what I wrote in the description: the replacement only happens if there is no similar box added yet (then the "skeleton" text can be fine-tuned afterwards).
Yes, it would be awesome if it did! But then we should add the version numbers for all functions... Uh, it sounds like huge pain. |
If it's a huge pain, maybe leave it as is for now. :) |
The |
By using the information available by the newly added
Deprecatedproperty, the deprecation warning boxes in the manual can now be generated when not exists. (if it already exists, the box may contain different alternative suggestion than what's written in the stub, so this case is not handled).