Function Documentation

WordPress Function Documentation Progress

Ohloh No Longer Criticizes WordPress Comment Ratio

Ohloh no longer lists the comment to code ratio as a factor for WordPress! This will hopefully improve as the PHP code base continues to be documented. Hopefully, once the focus is moved over to automated testing, the bugs and functionality will be improved to the point where WordPress will be rock solid.

This will hopefully limit the overall criticism that other developers have on WordPress. It will be a long road for complete documentation and quality assurance in WordPress. It is both fun and worthwhile learning experience. It is something that should have been in WordPress since the early days, but that isn’t important.

What is important is that not only should the quality of the WordPress feature set and defects reduce but the overall quality and assurance of that quality should be improved.


January 12, 2008 Posted by | WordPress | , , , , | Leave a comment

Informal Roadmap: Step 2 Completed

All items that could be documented in wp-includes folder has been documented with @since phpdoc tags. Which will allow for staying in that one file instead of going back and forth from web browser with version information to the editor. Will save time, I believe.

All that is left now is basically the following.

  1. Short Description
  2. Return type and description
  3. Parameter type and description
  4. Long Description

Now that the second step is completed, I’m going to focus more on completing the following files below. During that, I’m going to create tickets for the remain incomplete files that I’m not going to seek to finish. In that arena, there are only 20 incomplete files in wp-includes folder. If I complete the following files, I can get that number down to a more manageable 14. So that the next person that comes along shouldn’t feel a lot of weight on their shoulders.

In no particular order, I want to complete these files before the 14th of January 2008 is up. If I can complete at least 3, then I’ll be happy.

  • kses.phpalmost complete
  • pluggable.php – almost complete
  • comment.php – almost complete
  • cron.php
  • category.php
  • user.php

The most logical course of action is to finish up the almost complete files and have them committed as completed. Then start working on the rest of the easy files which shouldn’t take very long to complete. Probably should get cron.php started first since it is one of the most difficult with extremely sparse documentation. The category and user files will be worked on, in the event that there is more time left over.

So the goal jumped from 3 finished, to 4 finished and in one weekend. Wish me luck.

January 12, 2008 Posted by | WordPress | , , , , | Leave a comment

Writing Plugins: Does the filter or action exist?

This WordPress Plugin API feature is new to WordPress 2.5 and is quite interesting. Its application in plugins will be interesting to see when WordPress 2.5 is released.

The has_action() and has_filter() checks for the existent of hooks and whether a specific callback exists within the filter. This is useful, since it allows you to check whether anyone has added a callback to a specific hook. It also can prevent you from removing a callback that had already been removed.

Testing the Existence of a Hook

Hooks are only created when callbacks are added and in WordPress 2.5, when there remains at least one callback in the hook. If no callbacks are added to a hook or all callbacks are removed then both has_action($hook_name); and has_filter($hook_name); will return false.

This can be useful for creating your own filters for your plugin to see if anyone had hooked into your actions and filters. You can halt running the action or filter if there is nothing attached to the hook.

Removing Callbacks from Hooks

It used to be quite the process to test whether a callback existed and get the priority of the callback in order to remove it. These processes have been simplified in WordPress 2.5 and will make both finding and removing a known callback easier.

The key is that the callback has to be known. With classes, in 2.3.0 and the upcoming 2.5 release, there is a format for how classes are added as a callback. Fortunately, at least in 2.5 you don’t need to worry about the format. I’ll detail the format in a later post for those wanting to know in 2.3.x.

In WordPress 2.5 however, you only need to pass the same reference to the class and the method name. The way to get the reference, if you are removing the callback from another plugin’s class is to get the known global and use that reference.

If the plugin is known to cause problems with yours, then you should be able to get that information easily. It is easier if the offending plugin uses functions or static method calls as the original class reference variable is not needed.

Most of the hooks plugin authors will be removing will be WordPress internal ones, which don’t use classes. If this is the case, then the format is easier.

function myplugin_remove_offending_hook_after_test() {
    if( false !== ($priority = has_filter( 'pre_term_name', 'wp_filter_kses')) ) {
        remove_filter( 'pre_term_name', 'wp_filter_kses', $priority );
        // Hook another filter in its place.


When the second parameter is used, if the callback is found then the priority is returned. You can use this in the method above to remove the hook. As before, you must know the callback before hand.

The has_action() is used in the same way and as with add_filter() and add_action() it is always better to use the correct function for the hook you are referencing, even through they both use the same function.

January 12, 2008 Posted by | Writing Plugins Series | 2 Comments