Blog

In addition to the parallel project of WP-Parser for developer.wordpress.org there is another API reference called hookr.io. I first became aware of it through WP Tavern’s announcement earlier in the year Introducing Hookr.io: A New Resource For WordPress Developers.

After I wrote to WP Tavern to publicise WP-a2z.org, Jeff Chandler quite correctly asked “How does your reference differ from hookr.io” and “Is it any better you think than the one on developer.wordpress.org?”.

So I’ve had a good look at the latest incarnation of hookr.io and compared it with my own WP-a2z.org and developer.wordpress.org.

Brief overview of WP-a2z.org

WP-a2z implements a dynamic API reference for WordPress core, plugins and themes, with drill down navigation and called by or invoked by links.

It provides reference information for the PHP Files, Classes and APIs ( Functions and Methods ), plus the action hooks and filters.

In an attempt to reduce information overload the results that aid navigation are paginated.

While the name of the site suggests that pagination would be through links labelled A to Z, this hasn’t (yet) been implemented; it’s probably not the best way to navigate the code.

For more information see the Press release and a series of FAQ’s.

Quick review of hookr.io

Hookr.io seems to have come along in leaps and bounds. Initially restricted to a subset of WordPress, it now covers all hook invocations, actions and filters. It also displays classes, functions and shortcode invocations.

When viewing the source of a function you can drill down into other WordPress functions. But you can’t go up the call tree.

Hookr.io has an advanced AJAX user interface that takes a bit of learning and getting used to.

For example, it has some interesting JavaScript effects that blurs the code when you hover over it and some fancy colour coding beside links.

I’m glad to see that hookr.io has added plugins. Lots of them, if you know where to look: hookr.io/plugins.

There are parts of the function display that I particularly like e.g. links from signature parameters to the parameters table. But there are also other bits that are missing. e.g. the long description.

I don’t know what parser Christopher Sanford has used to build his solution but it would appear he’s had to deal with similar challenges to those faced by myself and the WP-Parser team.

• hookr.io does not yet parse classes into their methods.
• Nor does it actually display the files.

Given the complexity of the code and the slightly different approaches taken to parsing it, it’s no surprise that our results sets are slightly different.

Quick review of developer.wordpress.org

The Code reference part of WordPress.org is tucked away inside developer.wordpress.org at developer.wordpress.org/reference. There’s no direct link from WordPress.org.

The User Interface doesn’t seem to have improved much in the last few months.

Although we’re invited to “Search the codebase for documentation”, once you’ve found something the Code Reference search box disappears. You have to use breadcrumbs or the back button to perform another search.

In my opinion, developer.wordpress.org:

• doesn’t help you navigate the code,
• hasn’t really attempted to crack the mega data problem,
• nor is it nicely linked to or from the codex.

I know that a lot of good work has gone into formatting the parameters in the docblocks ( see register_post_type() ) , but until visitors to the codex see these automatically generated results, there will be little benefit.

Although WP-Parser is now being developed by a whole team of people, I feel that the results on developer.wordpress.org are still only usable as a reference when you don’t have the source code in front of you.

developer.wordpress.org also supports User Contributed Notes, though I have no idea how these are added!

Comparison of WP-a2z.org, hookr.io and developer.wordpress.org

Reference information

Implemented as post types or taxonomies /

None of the solutions provide

• An API reference for jQuery/JavaScript code
• The processing flow in common scenarios
• Where used trees for files
• Reference for global variable or class properties

In-source navigation

See also

File documentation

Only WP-a2z.org treats files as a separate post type.

When viewed the source file is dynamically parsed to determine the functions and classes implemented. These are stripped out and replaced by comments with links. The remaining code is then treated as an API, displaying:

• Syntax highlighted source with in-source navigation
• Called by – tbc
• Invoked by – tbc
• Calls
• Call hooks

See wp-login.php

Class documentation

Method documentation

For both WP-a2z and developer.wordpress.org the content displayed is the same as for Functions.

Function documentation

Hook documentation

WP-a2z.org and developer.wordpress.org treat action hooks and filters as the same post type.

hookr.io displays hooks in three ways

1. Hooks
2. Actions
3. Filters

It uses headings of Defined and Related to show where calls to add_action(), do_action(), apply_filters() are implemented. It also shows where remove_filter() is used.

These are similar to, but not quite the same as Invokers and Implementers.

See also and .

Constants

Currently only hookr.io displays information about Constants. The codex contains some information about commonly used constants.

Anything else?

The above tables reflect my understanding as of 3rd November 2014. Please advise any errors or omissions.

I’m sure there are many more properties that could be compared..

But the most important test of the API reference is a question you can ask yourself…

My honest answer, for all three solutions combined is “No. Not yet!”