Inline Docs Progress for 3.7

After last week’s weekly Inline Docs meeting we decided to begin doing a weekly ticket triage on Wednesdays.

As of last Wednesday, we’re happy to report that 19 patches have been committed to core from 12 different contributors. We’ve also updated the original make/core post to reflect the files that have been completed (please go claim some!). You can see the full report of last week’s triage on Trac. It’s really spectacular, and you should show some gratitude towards Drew for putting the report together.

Finally, beginning this week, our weekly inline-docs office hours are moving to #wordpress-sfd on Freenode. They’ll continue to be held on Wednesdays at 18:00 UTC, and we hope you can join us!

#3-7, #inline-docs

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

3.7 Inline Docs Office-Hours Meeting

It’s been awhile since you’ve heard from any of us about the inline-docs initiative for 3.7. We’ve been getting our ducks in a row, so to speak, and we’d like to start pounding pavement this week.

We’re going to hold an office-hours meeting on Wednesday, September 4 at 18:00 UTC in #wordpress-dev. We’ll review where we left off last meeting, cover the details on how we want to proceed, and make sure the details about getting involved really do show up here on Make/Core.

This meeting is mostly to help us on the planning team make sure we’re on the same page, but all are welcome. As I said, the next action steps for interested parties will get posted back here.

Thanks, too, for all of the encouragement around this. We’re pretty excited about it!

#3-7, #inline-docs

Better Inline Docs for 3.7

For the 3.7 cycle we’re going to focus hard on improving the inline docs throughout WP core. Eric Lewis, Drew Jaynes and myself will be leading this charge, and we invite anyone who is interested to join us.

You can join us for a meeting on the subject in #wordpress-dev IRC on Tuesday, August 13, 18:00 UTC.

For the first time ever, we’ll be adding inline docs to the many, many hooks found within core. This is the area I’ll be contributing the most, personally. Since we’ll mostly be marching to the beat of our own drum to document the hooks, so I’d like to use the remainder of this post to explain a bit more about our plan of attack – which we’ll discuss during Tuesday’s meeting.

Hook Doc Style

We’ll be using the same inline PHPDoc standard that is used for functions to documenting each of the hooks. This means both short description and long descriptions (where applicable), along with @since and @param tags. We will not be using the @return tag, however, because actions return nothing and filters simply return the first param.

The DocBlocks will appear, in almost every case, on the line directly preceding the call to do_action() or apply_filters. We feel this is the most logical placement when grokking the code as a human, and also the most convenient position for the parser that will power developer.wordpress.org.

Some Examples:

Note that in this third example we are using on the PHPDoc spec for describing hashes in order to document each of the passed items in the array. This, I think, provides a great deal of context for the array and a much greater value to our documentation (especially given the number of filters in core that pass arrays). As an aside, I agree that it may be odd we’re referencing the associative array keys as var names, rather than a string literal, but it’s necessary for parsing the docs properly.

Some Potential Issues

  1. I know there are a few hooks that appear in more than one location. In this case we’ll be documenting them in just one function and adding a pointer to that function across all other instances. We’ll determine the best way to handle this pointer in the weeks to come, for the immediate future I’ll just be using a shorthand comment for my own references.
  2. Many filters throughout core passed unnamed parameters and just embed the values of their parameters directly. In these instances I look first to core to see if an add_filter() is being called on the filter and then default to the var names passed there. If core is not calling the filter anywhere I’ve used names that seem most logical (e.g. $output)
  3. Several hooks have variable names. I don’e believe this will actually pose an issue, but I do want to make note of it.

Process

Because of the sheer volume of things we need to document, the best idea I’ve got so far (as recommended by Mark Jaquith) is to allow anyone willing to contribute an opportunity to “claim” the files they’d like to document. This would grant them a 2 day “lock” on the file(s) to document everything and submit a patch. This will help us minimize or eliminate duplicated efforts and stale patches as much as possible. We’ll likely have 2 separate tickets: one for documenting hooks, one for documenting functions, and all patches will be made directly to those tickets. This could become unwieldy, and we’ll discuss the merits of this approach in Tuesday’s meeting.

Don’t worry if you really want to help, but can’t attend the meeting. It will all be logged, and we’ll be posting updates back to the blog here (using the inline-docs tag). Once we get underway you’ll be able to track progress directly on the trac tickets.

Hope you’re as excited about this as I am!

#3-7, #inline-docs