[wp-trac] [WordPress Trac] #28841: Use markdown syntax for doc block lists

[WordPress Trac]

#28841: Use markdown syntax for doc block lists
--------------------------+-----------------------------
 Reporter:  coffee2code   |      Owner:
     Type:  defect (bug)  |     Status:  new
 Priority:  normal        |  Milestone:  Awaiting Review
Component:  General       |    Version:  3.9
 Severity:  minor         |   Keywords:  has-patch
  Focuses:  docs          |
--------------------------+-----------------------------
 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
 [http://make.wordpress.org/core/handbook/inline-documentation-standards
 /php-documentation-standards/#formatting-guidelines 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()`
 ([https://core.trac.wordpress.org/browser/tags/3.9/src/wp-
 includes/taxonomy.php#L269 src], which can be seen with its list displayed
 as a list
 [http://developer.wordpress.org/reference/functions/register_taxonomy/ on
 the Code Reference]).

 An example of an unformatted list is `wp_insert_user()`
 ([https://core.trac.wordpress.org/browser/tags/3.9/src/wp-
 includes/user.php#L1500 src],
 [http://developer.wordpress.org/reference/functions/wp_insert_user/ 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()`
 [https://core.trac.wordpress.org/browser/tags/3.9/src/wp-
 includes/post.php#L1485 does not] quote its keys, `get_posts()`
 [https://core.trac.wordpress.org/browser/tags/3.9/src/wp-
 includes/post.php#L1696 does].''

--
Ticket URL: <https://core.trac.wordpress.org/ticket/28841>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform