#38520 closed defect (bug) (fixed)
Add @return docs for interleave_changed_lines() (and prevent bad parsing)
| Reported by: | coffee2code | Owned by: | DrewAPicture |
|---|---|---|---|
| Priority: | normal | Milestone: | 4.9 |
| Component: | Revisions | Version: | |
| Severity: | normal | Keywords: | has-screenshots has-patch |
| Cc: | Focuses: | docs |
Description
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: 38520.bad-parsing.png)
Attached is a patch (38520.diff) to add documentation of the proper syntax and with better docs themselves.
![(please configure the [header_logo] section in trac.ini)](/chrome/site/your_project_logo.png)
Screenshot of DevHub showing bad parsing of function description due to poor syntax use