WordPress.org

Make WordPress Core

Opened 7 months ago

#38520 new defect (bug)

Add @return docs for interleave_changed_lines() (and prevent bad parsing)

Reported by: coffee2code Owned by:
Milestone: Awaiting Review Priority: normal
Severity: normal Version:
Component: General 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.

Attachments (2)

38520.bad-parsing.png (70.3 KB) - added by coffee2code 7 months ago.
Screenshot of DevHub showing bad parsing of function description due to poor syntax use
38520.diff (2.3 KB) - added by coffee2code 7 months ago.
Patch referenced in ticket (w/ whitespace fixes from original patch)

Download all attachments as: .zip

Change History (2)

@coffee2code
7 months ago

Screenshot of DevHub showing bad parsing of function description due to poor syntax use

@coffee2code
7 months ago

Patch referenced in ticket (w/ whitespace fixes from original patch)

Note: See TracTickets for help on using tickets.