Add Inline-Docs for Hooks

The time to document ALL THE HOOKS used throughout core is nigh.

We’ve hashed out the process in a couple of different meetings in #wordpress-dev, and we’ve added a new page to the Core Contributor Handbook that covers the broader PHPDoc standards, as well as the specific hook documentation standards (the praise for the bulk of that work should go to @kpdesign and @drewapicture, by the way).

At the bottom is a list of every file in core that has a call to either do_action() or apply_filters(). Files with a checkmark have been patched and are considered completed. Files marked with (username #xxxxx) are already claimed, and being worked on.

Directly below is the process we’re attempting to make sure each of these files can get patched swiftly with no duplicated nor wasted efforts.

How to contribute:

  1. Check the list first to make sure the file you want to work on hasn’t already been claimed.
  2. Update your local WordPress SVN or Git repo (use git pull) to the latest version of WordPress trunk (currently 3.9-alpha).
  3. Create a new ticket on Trac for the file.

    New Hook Docs Ticket Example

    • Format the title as “Hooks Docs: path/to/file.php”.
    • The Type should be “defect (bug)”.
    • Assign the ticket to the component the file is associated with.
    • Leave the Version blank.
    • Add the docs focus.
  4. Edit the file, and make a patch. Please make sure you create the patch from the root directory of your WordPress SVN or Git checkout.
  5. Upload your patch to the Trac ticket you created, and add the keyword “has-patch”.

*Note: We strongly encourage you to work on very few files at a time. In many cases, one at a time is probably best. In some cases it may make sense to tackle several at once. The important thing is that you realize your edits should be made and patched swiftly so that they aren’t invalidated by (or don’t invalidate) another patch. It’s also important to note that we’re working with a small time-table, and need to be able to claim, edit, patch quickly — which is hard to do if someone were to lay claim to 20 files at a time, and then sit on them for a few days.

Determining the since version for hooks

The recommended tool to use when searching for the version something was added to WordPress is svn blame. An additional resource for hooks is the WordPress Hooks Database. If, after using these tools, the version number cannot be determined, use @since Unknown.

Note: All @since tags should follow the three digit x.x.x format, unless it was ported from MU. Anything ported over from WPMU should use @since MU. Existing @since MU tags should not be changed.

Keeping Discussions Focused:

Any discussion about the specifics of a patch itself should happen on Trac. Any discussion about the broader scope of what we’re trying to do should take place during the weekly Inline Docs meeting on Wednesdays at 19:00 UTC in #wordpress-sfd.

Files needing patches:

Checked files are completed, marked files are claimed

Current status:

#3-7, #inline-docs