Inline Docs Progress for 3.7

After last week’s weekly Inline Docsinline docs (phpdoc, docblock, xref) meeting we decided to begin doing a weekly ticketticket Created for both bug reports and feature development on the bug tracker. triagetriage The act of evaluating and sorting bug reports, in order to decide priority, severity, and other factors. on Wednesdays.

As of last Wednesday, we’re happy to report that 19 patches have been committed to coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. 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 TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress.. 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 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. used throughout coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. 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 GitGit Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Git is easy to learn and has a tiny footprint with lightning fast performance. Most modern plugin and theme development is being done with this version control system. https://git-scm.com/. repo (use git pull) to the latest version of WordPress trunktrunk A directory in Subversion containing the latest development code in preparation for the next major release cycle. If you are running "trunk", then you are on the latest revision. (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 (bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority.)”.
    • Assign the ticketticket Created for both bug reports and feature development on the bug tracker. to the component the file is associated with.
    • Leave the Version blank.
    • Add the docs focus.
  4. Edit the file, and make 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.. Please make sure you create the patch from the root directory of your WordPress SVNSVN Subversion, the popular version control system (VCS) by the Apache project, used by WordPress to manage changes to its codebase. or Git checkout.
  5. Upload your patch to the TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. 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 Docsinline docs (phpdoc, docblock, xref) 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/CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress..

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 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