Better Inline Docs for 3.7

For the 3.7 cycle we’re going to focus hard on improving the inline docsinline docs (phpdoc, docblock, xref) throughout WP coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.. 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 IRCIRC Internet Relay Chat, a network where users can have conversations online. IRC channels are used widely by open source projects, and by WordPress. The primary WordPress channels are #wordpress and #wordpress-dev, on irc.freenode.net. on Tuesday, August 13, 18:00 UTC.

For the first time ever, we’ll be adding inline docs to the many, many hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. 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 PHPDocPHPDoc (docblock, inline docs) 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 tagtag A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.), 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.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/.

Some Examples:



This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters


<?php
/**
* The location to send commenter after posting
*
* @since 1.5.0
*
* @param string $location The 'redirect_to' URI sent via $_POST
* @param object The comment object
*/
$location = apply_filters('comment_post_redirect', $location, $comment);



This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters


<?php
/**
* Return the ID of the uploaded attachment of a given type
*
* @since 2.5.0
*
* @param int $id The uploaded attachment ID
*/
echo apply_filters("async_upload_{$type}", $id);



This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters


<?php
/**
* Allow definition of default variables
*
* @since MU
*
* @param array $user_data The user data to define {
* @type string $user_name The username
* @type string $user_email The user's email
* @type array $errors
* }
*/
$filtered_results = apply_filters('signup_user_init', array('user_name' => $user_name, 'user_email' => $user_email, 'errors' => $errors ));
view raw

wp-signup.php

hosted with ❤ by GitHub

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 filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. 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 patchpatch A special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff. A patch can be applied to a codebase for testing.. 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 blogblog (versus network, site) here (using the inline-docs tag). Once we get underway you’ll be able to track progress directly on the tracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. tickets.

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

#3-7, #inline-docs