Hook Docs (5): wp-admin/includes/upgrade.php

[jackreichert]

wp-admin/includes/upgrade.php is missing documentation for the hook filters.

[jackreichert]

patch containing said missing documentation

[jackreichert]

typo fixed

[DrewAPicture]

Hi Jack, thanks for the patch! Here are some notes on 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 :)

[jackreichert]

Thanks DrewAPicture for your detailed response, I know it would have been quicker for you do fix it yourself. I appreciate it. I'm using a new editor, I thought I got the tabs worked out, I'll look into that.

Uploaded a new patch. I think this one is closer to the mark.

[jackreichert]

reworked language, spacing.

[vancoder]

Correcting notation syntax, making descriptions more consistent

[DrewAPicture]

Thanks for the new patch, Grant. Works for me.

[DrewAPicture]

Final pass.

[DrewAPicture]

In 27965:

Inline documentation for remaining hooks in wp-admin/includes/upgrade.php.

Props jackreichert, vancoder.
Fixes #27646.