#38520 closed defect (bug) (fixed)
Add @return docs for interleave_changed_lines() (and prevent bad parsing)
Reported by: | coffee2code | Owned by: | DrewAPicture |
---|---|---|---|
Milestone: | 4.9 | Priority: | normal |
Severity: | normal | Version: | |
Component: | Revisions | Keywords: | has-screenshots has-patch |
Focuses: | docs | Cc: |
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.
Screenshot of DevHub showing bad parsing of function description due to poor syntax use