[wp-meta] [Making WordPress.org] #1647: Improve deprecation notice banner text generation.

[Making WordPress.org]

#1647: Improve deprecation notice banner text generation.
-------------------------------------+-----------------
 Reporter:  coffee2code              |      Owner:
     Type:  defect                   |     Status:  new
 Priority:  normal                   |  Milestone:
Component:  developer.wordpress.org  |   Keywords:
-------------------------------------+-----------------
 Currently, the text that appears in the deprecation notice banner for
 deprecated resources consists of two parts:

 1. The boilerplate `This {$content_type} has been deprecated.`
 2. And, if possible, an additional message referring visitors to an
 alternative resource e.g. `Use other_function() instead.`.

 The message for part two is currently solely derived from the presence of
 a `@see` tag that ostensibly points to the alternative function, which is
 fine for many cases, but not in the case for others.

 Proposed improvements:
 1. For some reason, the parser sometimes drops the ending '()' from
 functions and methods mentioned via `@see`, so restore those for display
 if appropriate.
 2. If the function does not specify a `@see` tag, then attempt to use the
 message provided with the `@deprecated` tag. (Note: the `@see` is
 preferred over the more direct `@deprecated` because the generated message
 is translatable whereas the `@deprecated` message is not.)
 3. If the `@deprecated` message is used, append 'instead.' to the string
 if not already present. Many deprecated notices are of the syntax `Use
 other_function()` rather than the preferred `Use other_function()
 instead.`. This makes the message consistent regardless of how it was
 derived.

--
Ticket URL: <https://meta.trac.wordpress.org/ticket/1647>
Making WordPress.org <https://meta.trac.wordpress.org/>
Making WordPress.org