[wp-trac] [WordPress Trac] #27646: Hook Docs (5): wp-admin/includes/upgrade.php

[WordPress Trac]

#27646: Hook Docs (5): wp-admin/includes/upgrade.php
-----------------------------+------------------------------
 Reporter:  jackreichert     |       Owner:
     Type:  defect (bug)     |      Status:  new
 Priority:  normal           |   Milestone:  Awaiting Review
Component:  Upgrade/Install  |     Version:
 Severity:  normal           |  Resolution:
 Keywords:  needs-patch      |     Focuses:  docs
-----------------------------+------------------------------
Changes (by DrewAPicture):

 * keywords:  has-patch => needs-patch


Comment:

 Hi Jack, thanks for the patch! Here are some notes on
 [attachment:docs.upgrade.php-1.diff]:

 Overall:
 * Per core coding standards, we use tabs instead of spaces for
 indentation. Looks like some of the lines use tabs, some use spaces, which
 is probably why the spacing looks weird in the patch.
 * All short descriptions and parameter descriptions should end with
 periods.

 `dbdelta_queries` filter:
 * The `$queries` parameter is actually an array of queries.
 * In describing filters we try to avoid saying *why* something is
 filterable, and rather explaining *what* is filterable. So in this case,
 something as simple as "Filter the dbDelta queries." should suffice. If
 you want to provide more detail in the long description, that's fine too.

 `dbdelta_create_queries` and `dbdelta_insert_queries` filters:
 * The `$cqueries` and `$iqueries` parameters are both of the array type.
 * Rather than just describing `$cqueries` as "dbdelta create queries" or
 `$iqueries` as "dbdelta insert queries", perhaps you could be more
 descriptive? What is a "create query"? What is dbDelta, for that matter?
 The entire goal of hook docs is to explain beyond the immediately obvious
 :)

--
Ticket URL: <https://core.trac.wordpress.org/ticket/27646#comment:3>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform