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