Improve deprecation notice banner text generation.

Description

Currently, the text that appears in the deprecation notice banner for deprecated resources consists of two parts:

The boilerplate This {$content_type} has been deprecated.

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:

For some reason, the parser sometimes drops the ending '()' from functions and methods mentioned via @see, so restore those for display if appropriate.

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.)

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.