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

[coffee2code]

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.

[coffee2code]

Patch referenced in ticket.

[DrewAPicture]

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]

Markdown list fixes

[DrewAPicture]

To convert to hash notations

[DrewAPicture]

• 28841.2.diff​ contains the proposed markdown list fixes
• 28841.3.diff​ contains the yet-to-be-converted hash notation fixes

[DrewAPicture]

In 29107:

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

Props coffee2code for the initial patch.
See #28841.

[DrewAPicture]

In 29108:

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

Props coffee2code for the initial patch.
See #28841.

[DrewAPicture]

In 29109:

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

See #28841.

[DrewAPicture]

In 29111:

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

Props coffee2code for the initial patch.
See #28841.

[DrewAPicture]

In 29112:

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

Props coffee2code for the initial patch/
See #28841.

[DrewAPicture]

In 29113:

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

Props coffee2code for the initial patch.
See #28841.

[DrewAPicture]

In 29115:

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

See #28841.

[DrewAPicture]

In 29116:

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

See #28841.

[DrewAPicture]

In 29128:

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

See #28841.

[DrewAPicture]

In 29129:

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

See #28841.

[kpdesign]

What's left to be done on this ticket?

[DrewAPicture]

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

[DrewAPicture]

In 31600:

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

See #28841.