do_blocks(): Document optimization from #63588

[dmsnell]

See #63588

When the transient-memory-leak was optimized-away in #63588 it was added without an explanatory comment. This leaves the code prone to accidental removal by someone coming along and thinking that there is extra work being done.

The optimization should be documented so that there’s a stronger guard against accidental and well-intentioned-yet-harmful regression.

Trac ticket: Core-63616
See #8999

Adds explanatory comment indicating why the optimization was added and guarding against accidental removal.

This is a documentation-only change and should include no functional or visual changes.

[swissspidy]

Can we just reopen the original ticket and link the commit there please? :-)

[dmsnell]

Duplicate of #63588.

Oh sure @swissspidy — sorry I didn’t think to do that.

@audrasjb I’m open to that, though I would need help with knowing what link you’re referring to. do you mean removing this inline link entirely and adding another PHPDoc token below on a line of its own, * @see parse_blocks()?

This docblock won't be fetched by the docblock, parser as it is not a function or a hook

Right, so I think this only affects an in-IDE experience, for which I was trying to optimize.

providing the link is probably better than using a relative reference

I don’t think I know what you are referring to with “relative reference”. I did some testing an indeed, were this docblock inside a class it would resolve to the class method of the same name. With namespaces it follows the module namespace.

I’ll wait for clarification, but in the meantime I’ve added a leading \ which should resolve all ambiguity in referencing the name.