Improve deprecation notice banner text generation.

[coffee2code]

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.

[coffee2code]

In 2816:

developer.wordpress.org: Improve deprecation notice banner text generation.

• Add '()' to functions and methods on display, if dropped by parser.
• Fall back to @deprecated message if no @see is present.
• Append 'instead.' to string taken from @deprecated if not already present.

Fixes #1647.