Make WordPress Core

Opened 8 years ago

Closed 7 years ago

Last modified 7 years ago

#38520 closed defect (bug) (fixed)

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

Reported by: coffee2code's profile coffee2code Owned by: drewapicture's profile 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.

Attachments (2)

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

Download all attachments as: .zip

Change History (5)

@coffee2code
8 years ago

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

@coffee2code
8 years ago

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

#1 @DrewAPicture
7 years ago

  • Milestone changed from Awaiting Review to 4.9

#2 @DrewAPicture
7 years ago

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

In 40971:

Docs: Add full parameter and return documentation for WP_Text_Diff_Renderer_Table::interleave_changed_lines().

Props coffee2code.
Fixes #38520.

#3 @SergeyBiryukov
7 years ago

  • Component changed from General to Revisions
Note: See TracTickets for help on using tickets.