I’ve been sitting on this one for a while, because I’ve been waiting to finish a few features. This one feature is still not complete, but I did something today using Google’s new Coop system that merits a little attention.
You may have visited RedAlt before for various reasons. RedAlt houses a cross-reference of WordPress source code, not just for the trunk (current in-development code), but for both the 2.0 branch (which is the current in-release version), and 1.5.2. These are generated with PHPXref, a tool (written in Perl?) that parses the PHP source code and creates all the links to output and such. So that’s pretty cool. There are a few installations of the XRef’ed WordPress code in various places on the net, but I’m not sure that all of those sites provide XRefs for prior WordPress versions, which may be of use if you’re still using the stable versions of old.
Also on RedAlt you can find the brand new Developer Function Reference. There are a few unique things about the function reference that set it apart from the XRef. First, one goal of the Reference is to provide documentation for the WordPress functions, which is something that an XRef alone doesn’t do.
You’ll note that many of the functions do not currently have definitions, and that’s where you come in. You can create an account at RedAlt, which will allow you to edit the descriptions of the functions. After you are logged in, you simply click on the thing you want to edit and through a bit of Ajax magic, an editor appears.
The other major goal of the Function Reference is to be able to produce output in the form of a diff that you can patch into a copy of the WordPress source. When applied, the patch would insert PHPDoc function information for every function in the codebase. Even without every function being documented, this provides some utility to developers who use an IDE that supports PHPDoc.
There is one issue remaining with the patch functionality (very small functions cause overlaps in the diff algorithm, which causes patch to choke when the diff is applied), and as soon as that is worked out, I’ll mention it.
The parser on RedAlt that generates this documentation watches for function declarations and new PHPDoc in the source. It can capture and merge this information into the documentation. The only thing that it doesn’t do well is when someone (Ryan!) moves a function from one file to another, which causes some odd dual-counting issues that I have to address by hand. Apart from that, the process is pretty automated.
I have been told that such a utility could be useful to other PHP-based projects, since building developer documentation seems to be a common task that PHP devs often never get around to. This certainly makes it easier. I’ll have to consider that, too.
The interesting thing that I did today was use Google’s Coop features to create a search subscription to the function reference. The end result is that if you search for a function name in Google, RedAlt function reference info is returned.
It’s very easy to activate this functionality in Google. Go to my Coop profile and click the Subscribe button. Then, if you search for “the_content”, Google will return the URL to RedAlt and the basic function call information, including parameters.
Maybe I can convince Mark to open some API to his plugin hook reference, and then hooks can be searched the same way.
I’m not particularly satisfied with the way Google requires this information to be published, but we’ll see how it works out for now. The current process requires that I feed them a custom form of XML with every possible search result. The reference, even in its incomplete form, is a 1MB download every time it’s spidered. Gah! Plus, it’s not possible using this technique to guess at what functions a person might be looking for.
For example, if someone searches for “wordpress function output the author URL”, then they are looking for the function “the_author_URL()”. But because Google’s indexing of these keywords is static, I would have to supply them with the literal text for every possible search phrase that would result in finding the appropriate function. Instead it would be handy if Google would look for a couple of keywords (like “wordpress function”) and then feed the rest of the query to a REST service, where possible results could be accumulated. This could be overridden by their current static approach, but this seems like an option that would generate more valid results and answer more queries.
In case anyone else is interested in tapping the RedAlt Reference programmatically, I do have a REST API for it, in case you want to request information about functions for some site of your own. Matt Read has been using the API in his JibbyBot on #wordpress IRC to provide function reference directly in the IRC channel. Pretty darn handy.
See what you think, make feature requests here or on the RedAlt support forum.
