Coming Soon: Inline Documentation For All WordPress Hooks

all-the-hooksSomething exciting is happening in the world of WordPress documentation. Very soon all of the hooks used throughout the core are going to be documented. An initiative is now underway to bring inline docs for hooks into the upcoming WordPress 3.7 release. I can see some of you jumping up and down and celebrating wildly right now. But there are probably more than a few of you who are wondering “What in the world is a hook?”

You will see the terms “actions/filters” and “hooks” throughout the codex and it can get a little confusing. Hooks are split into actions and filters. Essentially, hooks are events that allow you to “hook” into WordPress and make it do stuff. The codex Plugin API/Action Reference page lists all existing hooks, some of which have been documented.

Inline documentation of hooks will make it much easier for developers to extend WordPress. Each hook gets a quick explanation and the @since version added as a comment. For example, check out the notes for do_action( ‘welcome_panel’ );

welcome-panel

If you wanted to add some content to the WordPress welcome panel but didn’t know how, this inline documentation will help to point you in the right direction.

A handful of contributors are currently tackling a massive list of hooks in 195 files. If you can help, leave a comment on the make.wordpress.org post to claim the files you’ll be working on and then add separate patches for each to the Add Inline Docs for Hooks trac ticket. Make sure to review the hook documentation standards before submitting a patch.

Developers always say that if you want to learn WordPress, the best way to start is by going through the core to find out how it all works. Inline documentation for hooks will make this easier than ever. Although it’s a monumental task to coordinate, the end result is that WordPress will be much more approachable for developers who are new to the platform.

10 Comments


  1. This is great news for WordPress core docs. The more comments in core the better, especially for new users!

    Report


  2. Well, the complete documentation also has to be added to the Codex, otherwise it isn’t really useful. Finding how the stuff works while browsing through random code isn’t very user-friendly. Ain’t nobody got time for that.

    Report


  3. Hi Sarah, I’m one of the leaders of the inline docs initiative for 3.7 (and beyond).

    I notice you didn’t mention the forthcoming Code Reference, which will live at develop.wordpress.org and is in actuality the driving force behind documenting these hooks and filters.

    The Code Reference will use a parser to pull the inline docs of hooks, filters, functions, and classes into a dynamic web reference (similar in many ways to queryposts.com). So if the docs aren’t there, they won’t get parsed, thus the big push!

    It’s also important to keep in mind that ultimately the Code Reference will in-effect replace huge chunks of the Codex, including the Function Reference, Class Reference, Filter Reference and a bunch of other stuff. We’ll bring together vetted examples and other interactivity we would have had to manually generate before.

    And yes, it’s definitely about making extra information about all hooks and filters more readily available to anybody who wants to know.

    If you’d like to know more about future plans of documenting WordPress, check out the roadmap we developed over the summer.

    Report


  4. excellent stuff. its much needed.

    Report


  5. Great news! Documented hooks… what else can web ask for?

    Report


  6. @Devtard – The Codex will be disappearing in the future in one form or another. Instead, most of this stuff will be added to the Develop.WordPress.org site mentioned by Drew. Some of it may also end up in a handbook.

    This is one of those huge efforts that may get unnoticed in the future but I’m glad Brian Richards, Drew and others are going through with it. It’s one of those things that if it gets done now, it will have huge positive gains for the future.

    Report


Comments are closed.