[wp-trac] [WordPress Trac] #38520: Add @return docs for interleave_changed_lines() (and prevent bad parsing)

[WordPress Trac]

#38520: Add @return docs for interleave_changed_lines() (and prevent bad parsing)
--------------------------+---------------------------------------
 Reporter:  coffee2code   |      Owner:
     Type:  defect (bug)  |     Status:  new
 Priority:  normal        |  Milestone:  Awaiting Review
Component:  General       |    Version:
 Severity:  normal        |   Keywords:  has-screenshots has-patch
  Focuses:  docs          |
--------------------------+---------------------------------------
 For `interleave_changed_lines()` in `WP_Text_Diff_Renderer_Table`, the
 return value is documented rather sparsely and poorly in the description
 and not documented in `@return` except as being an array. (In fact, it is
 slightly better documented in a comment preceding its sole invocation, in
 `_changed()`.)

 This existing documentation utilizes a glob-style notation that fails to
 accurately indicate the exact return value array elements to be expected.
 Additionally, this unnecessary notation gets misinterpreted as Markdown by
 WP-Parser, resulting in a mangled description for the function in
 developer.wordpress.org (appearing as partially italicized text and a
 stray text in a code block).

 See:
 https://developer.wordpress.org/reference/classes/wp_text_diff_renderer_table/interleave_changed_lines/
 (or for posterity: [attachment:38520.bad-parsing.png])

 Attached is a patch ([attachment:38520.diff]) to add documentation of the
 proper syntax and with better docs themselves.

--
Ticket URL: <https://core.trac.wordpress.org/ticket/38520>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform