Opened 8 years ago

Closed 8 years ago

#1647 closed defect (bug) (fixed)

Improve deprecation notice banner text generation.

Reported by: coffee2code's profile coffee2code Owned by: coffee2code's profile coffee2code
Milestone: Priority: normal
Component: Developer Hub 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.

Change History (1)

#1 @coffee2code
8 years ago

  • Owner set to coffee2code
  • Resolution set to fixed
  • Status changed from new to closed

In 2816: 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.

Note: See TracTickets for help on using tickets.