WordPress.org

Make WordPress Core

Opened 5 years ago

Closed 5 years ago

Last modified 5 years ago

#28841 closed task (blessed) (fixed)

Use markdown syntax and/or hash notations for doc block lists

Reported by: coffee2code Owned by:
Milestone: 4.1 Priority: normal
Severity: minor Version: 3.9
Component: General Keywords: has-patch
Focuses: docs Cc:
PR Number:

Description

The doc blocks for various functions enumerate items via lists (namely to document supported array arguments). However, not all of the function doc blocks use the markdown list syntax in doing so. Not only is this internally inconsistent, it violates the formatting guidelines, which also prevents the lists from being rendered as lists in the Code Reference.

An example of a function with a properly formatted list in its doc block is register_taxonomy() (src, which can be seen with its list displayed as a list on the Code Reference).

An example of an unformatted list is wp_insert_user() (src, as seen on Code Reference) (which also in this case and others, not using the markdown list syntax causes indented line continuations to be treated as code blocks).

Eventually the hard breaks the Code Reference currently inserts for newlines between consecutive lines of text during import/display will be removed, leaving these non-lists to merge into a single paragraph/run-on sentence.

The attached patch corrects the doc block list formatting found in wp-includes/*.

In most cases, the list syntax is being added to what is simply a newline-separated list of items. In a few cases, explicit list HTML (also a formatting guideline violation) is being replaced with the markdown syntax. In one case (get_terms() in taxonomy.php) a multi-paragraph formatted list is reformatted into an actual list.

Files affected:

  • bookmark-template.php (2 functions)
  • bookmark.php (1 function)
  • class-http.php (2 functions; HTML removal)
  • functions.php (1 function)
  • general-template.php (1 function; HTML removal)
  • post.php (1 function)
  • post-template.php (1 function; HTML removal)
  • shortcodes.php (1 function)
  • taxonomy.php (1 function)
  • user.php (2 functions)
  • wp-db.php (1 function)

* Undoubtedly, most, if not all, of these problem lists would be moved into the appropriate @param documentation rather than remaining in the function's long description, as has already recently been done for register_post_status() and register_post_type(). Which may be the true fix, but until then...

* There is also an inconsistency with the presence of single quotes around a list key item (the array keys being documented), which is not addressed in this patch. For example: get_post_type_labels() does not quote its keys, get_posts() does.

Attachments (3)

28841.diff (30.9 KB) - added by coffee2code 5 years ago.
Patch referenced in ticket.
28841.2.diff (5.3 KB) - added by DrewAPicture 5 years ago.
Markdown list fixes
28841.3.diff (25.6 KB) - added by DrewAPicture 5 years ago.
To convert to hash notations

Download all attachments as: .zip

Change History (20)

@coffee2code
5 years ago

Patch referenced in ticket.

#1 @DrewAPicture
5 years ago

  • Milestone changed from Awaiting Review to Future Release
  • Type changed from defect (bug) to task (blessed)

#2 @DrewAPicture
5 years ago

Thanks for the patch and the ticket. Some of these actually need to be converted into hash notations, so I'll probably split it into several patches just to reduce confusion.

@DrewAPicture
5 years ago

Markdown list fixes

@DrewAPicture
5 years ago

To convert to hash notations

#3 @DrewAPicture
5 years ago

#4 @DrewAPicture
5 years ago

In 29107:

Convert default arguments documentation for WP_Http_Cookie::construct() into a hash notation.

Props coffee2code for the initial patch.
See #28841.

#5 @DrewAPicture
5 years ago

In 29108:

Convert default arguments documentation for _walk_bookmarks() and wp_list_bookmarks() into hash notations.

Props coffee2code for the initial patch.
See #28841.

#6 @DrewAPicture
5 years ago

In 29109:

Add indentation for the hash notation missed in [29108].

See #28841.

#7 @DrewAPicture
5 years ago

In 29111:

Convert default arguments documentation for get_bookmarks() into a hash notation.

Props coffee2code for the initial patch.
See #28841.

#8 @DrewAPicture
5 years ago

In 29112:

Convert default arguments documentation for wp_page_menu() into a hash notation.

Props coffee2code for the initial patch/
See #28841.

#9 @DrewAPicture
5 years ago

In 29113:

Convert default arguments documentation for get_posts() into a hash notation.

Props coffee2code for the initial patch.
See #28841.

#10 @DrewAPicture
5 years ago

In 29115:

Convert default arguments documentation for wp_dropdown_users() into a hash notation.

See #28841.

#11 @DrewAPicture
5 years ago

In 29116:

Convert default arguments documentation for wp_insert_user() into a hash notation.

See #28841.

#12 @DrewAPicture
5 years ago

In 29128:

Convert default arguments documentation for get_terms() into a hash notation.

See #28841.

#13 @DrewAPicture
5 years ago

In 29129:

Add indentation for the hash notation missed in [29128].

See #28841.

#14 @DrewAPicture
5 years ago

  • Summary changed from Use markdown syntax for doc block lists to Use markdown syntax and/or hash notations for doc block lists

#15 @kpdesign
5 years ago

What's left to be done on this ticket?

#16 @DrewAPicture
5 years ago

  • Milestone changed from Future Release to 4.1
  • Resolution set to fixed
  • Status changed from new to closed

Let's call this fixed. We'll cover anything left in #28298.

#17 @DrewAPicture
5 years ago

In 31600:

Properly indent the hash notation of default arguments for wp_page_menu().

See #28841.

Note: See TracTickets for help on using tickets.