Make WordPress Core

Opened 10 years ago

Closed 10 years ago

#27646 closed defect (bug) (fixed)

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

Reported by: jackreichert's profile jackreichert Owned by: drewapicture's profile 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 10 years ago.
patch containing said missing documentation
docs.upgrade.php-1.diff (1.3 KB) - added by jackreichert 10 years ago.
typo fixed
docs.upgrade.php-2.diff (1.6 KB) - added by jackreichert 10 years ago.
reworked language, spacing.
27646.patch (1.5 KB) - added by vancoder 10 years ago.
Correcting notation syntax, making descriptions more consistent
27646.2.patch (1.3 KB) - added by DrewAPicture 10 years ago.
Final pass.

Download all attachments as: .zip

Change History (11)

@jackreichert
10 years ago

patch containing said missing documentation

@jackreichert
10 years ago

typo fixed

#1 @kpdesign
10 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
10 years ago

  • Keywords has-patch added; needs-patch removed

#3 @DrewAPicture
10 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
10 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
10 years ago

reworked language, spacing.

@vancoder
10 years ago

Correcting notation syntax, making descriptions more consistent

#5 @DrewAPicture
10 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
10 years ago

Final pass.

#6 @DrewAPicture
10 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.