WordPress.org

Make WordPress Core

Opened 7 years ago

Closed 7 years ago

#27646 closed defect (bug) (fixed)

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

Reported by: jackreichert Owned by: DrewAPicture
Milestone: 3.9 Priority: normal
Severity: normal Version:
Component: Upgrade/Install Keywords: has-patch commit
Focuses: docs Cc:

Description

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

Attachments (5)

docs.upgrade.php.diff (1.3 KB) - added by jackreichert 7 years ago.
patch containing said missing documentation
docs.upgrade.php-1.diff (1.3 KB) - added by jackreichert 7 years ago.
typo fixed
docs.upgrade.php-2.diff (1.6 KB) - added by jackreichert 7 years ago.
reworked language, spacing.
27646.patch (1.5 KB) - added by vancoder 7 years ago.
Correcting notation syntax, making descriptions more consistent
27646.2.patch (1.3 KB) - added by DrewAPicture 7 years ago.
Final pass.

Download all attachments as: .zip

Change History (11)

@jackreichert
7 years ago

patch containing said missing documentation

@jackreichert
7 years ago

typo fixed

#1 @kpdesign
7 years ago

  • Focuses docs added
  • Keywords needs-patch added
  • Summary changed from Hook Docs wp-admin/includes/upgrade.php to Hook Docs (5): wp-admin/includes/upgrade.php

#2 @kpdesign
7 years ago

  • Keywords has-patch added; needs-patch removed

#3 @DrewAPicture
7 years ago

  • Keywords needs-patch added; has-patch removed

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 :)

#4 @jackreichert
7 years ago

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
7 years ago

reworked language, spacing.

@vancoder
7 years ago

Correcting notation syntax, making descriptions more consistent

#5 @DrewAPicture
7 years ago

  • Keywords has-patch commit added; needs-patch removed
  • Milestone changed from Awaiting Review to 3.9

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

@DrewAPicture
7 years ago

Final pass.

#6 @DrewAPicture
7 years ago

  • Owner set to DrewAPicture
  • Resolution set to fixed
  • Status changed from new to closed

In 27965:

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

Props jackreichert, vancoder.
Fixes #27646.

Note: See TracTickets for help on using tickets.