Function Documentation

WordPress Function Documentation Progress

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: Getting the Current Hook

WordPress 2.5 adds the ability to get the current hook name. This is useful for when you have a function for a filter which needs to return different output by the hook name.

A little bit of History

I didn’t agree with the idea, but the patch put forward was clean and neat. The implementation really moves the progress of the WordPress 2.5 Plugin API forward. The reasoning behind the implementation is that there are several times where a single function needs to be used for different hooks but still do somewhat different things depending on each hook.

My suggestion was to create two functions for each hook, but after some time debating I eventually supported the idea. While I didn’t supply the patch, or at least not the patch that was committed to core, I do think debating the idea made for a better feature.

How to get the Current Hook

The current hook can be retrieved using the current_filter() function. It will return a string that has the name of the hook within the context of the function that is called within the hook.

To further explain, lets say that Hook_A has three functions and the second function calls Hook_B, which has one function. When the one function in Hook_B calls current_filter(), it will return ‘Hook_B’. When the three functions in Hook_A call current_filter(), it will return ‘Hook_A’.

It will always be this way since, PHP does not do multithreading to allow for current_filter() to process two hooks at the same time. So it can always be assumed that the value in current_filter() will always return the current filter that the function was hooked into.

Example Plugin

The example plugin strips tags in the ‘wp_title’ hook and in the ‘wp_content’ hook, but also calls wpautop for ‘wp_content’ hook.

add_filter('wp_title', 'myplugin_sanitize');
add_filter('wp_content', 'myplugin_sanitize');

function myplugin_sanitize($content) {
    $content = strip_tags($content);

    if( 'wp_content' == current_filter() )
        $content = wpautop($content);

    return $content;
}

So we reduced what would be two functions into one and reduced the footprint of the total plugin code.

For filtering it is useful to sanitize something for everything except for a few areas or allow for different hooks to have different allowable items, but not for others. While it is possible to write several functions for each one, it is better (arguably) to have everything in one function for maintainability.

January 11, 2008 Posted by | Writing Plugins Series | , , | Leave a comment

Informal Roadmap: Step 1 Completed

I finished the first step of the informal roadmap for the wp-includes folder. I’m halfway through with completing the second step, but really, it isn’t so hard to complete those steps. Steps 3, 4, and 5 are the most difficult and time consuming ones to complete.

As always, I’m working on fully completing several files while completing the rest of the steps. I figure if I complete the steps, it won’t seem as difficult and time consuming and I can get many files completed at once.

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

Writing Plugins: The ‘all’ Hook

The ‘all’ hook is run on every action and filter hook. It is good for debugging and not much else. Also, prior to WordPress 2.5, the ‘all’ hook was broken and shouldn’t be hooked into.

The fix removes the logic that merges the all hook into the rest of the other hooks. This should have a nice benefit of speeding up the plugin cycle. The all hook will also only be processed if there is a function that was added to it. For almost all users, they will never run the all hook.

The ‘all’ hook is technically an action since it does not offer an interface for returning data to other functions that are in the ‘all’ hook. However, it will run for all actions and filters, but will not have access to the filter contents.

Well, for filters, the ‘all’ hook will have access to the initial parameter value or values if there is more than one parameter (more on that later), but will not have access to the completed value after all of the functions in the hook have processed the initial value.

Adding a Function to the ‘all’ Hook

add_action('all', 'myplugin_all_hook');

function myplugin_all_hook( $parameters ) {
    // Do stuff here
}

The all hook has access to the parameters that were passed to the hook as an array and that will be passed to the functions. The ‘all’ hook does not have access to manipulate those parameter values before they get to the filter or action functions.

The $parameters is an array, which holds all of the values for from each of the parameters. You can count the array, test the contents of the parameters, test the types of the values.

Use Cases

What the ‘all’ hook can do however is a few evaluations.

  1. Do sanity checks against how many parameters the current hook (Will be discussed in a later post) should have verses how many were actually passed.
  2. Count how many times a hook was called during a run of WordPress and for each page. (The ‘all’ hook will not be able to profile how long each hook took to process however.)
  3. Using debug_backtrace(), can figure out which functions called the hook.
  4. Fine tune your plugin by seeing what the hook you are plugin to is giving your function.

Those are the common use cases of the ‘all’ hook. However, like it has already been stated, only debuggers are likely to plugin to the ‘all’ hook. Most plugin authors and users should not concern themselves. However, if you wish to debug the hooks, then there is a built-in way to do so.

January 10, 2008 Posted by | Writing Plugins Series | , , , | Leave a comment

State of WordPress Documentation

The Codex

Perhaps the most definitive guide for WordPress is the codex and perhaps the few books that are out. However, the books can never cover the full scope of all that is WordPress. The codex focuses on a lot of subjects that is WordPress but does not cover everything that a user and developer needs.

That is probably the biggest problem with both the codex and books. What do you cover? What should be covered. Do you hold the user’s hand for the first few steps or do you ride the whole way making sure that the user stays on the correct path? For the codex, it is the former, it only holds your hand for a little while and the contents of which you have to find yourself.

That is not to say that the codex isn’t the best resource you have. It is. It is only to say that it will only take you so far before you have to help yourself.

Debate Against WordPress Inline Documentation

There shouldn’t have been a debate, early on in whether inline documentation should be included in the core. Before late 2006, early 2007, the consensus from the core team was that inline documentation wouldn’t make it into the official WordPress repository. Attempts to add inline documentation were blocked and that was a big mistake.

It is only speculation, but in my opinion by blocking the potential authors of said documentation, they essentially killed their motivation to do it. Those that initially started would shot down before they were able to prove whether or not they could complete the documentation. It would be another year before another person would come along. Like anything it is unknown whether that person would be able to complete all of the documentation before moving on to something more shiny.

It created other problems, because created debates about adding documentation. Which to long readers of the WordPress hackers list, seemed redundant, because the subject had been beaten to death many times before. There was even a debate over the standard of inline documentation, when a standard already existed before the debate started. It was time that would have been better spent following the current standard and working on the documentation.

That discussion was in October 2007 and there were many discussions before that. The codex page for Inline Documentation lists a few, but not all.

Current Effort

The current effort was picked up in October of 2007 and ended January 2008. A large amount of functions were documented, but it is far from complete. The wp-admin/includes folder also needs to have a phpdoc effort started for it.

It seems that every six months or so, discussion picks up and motivation is gained for completing the documentation, so perhaps in six months to a year some awesome person will come along again and finish the effort that has been started by so many people.

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

Writing Plugins: Activation and Deactivation

WordPress provides hooks for when the plugin is activated and deactivated. Some plugins will have logic in their init function which check to see if set up or installed itself and if it didn’t it would install or upgrade itself.

The upgrader check can still remain in the init function, a user might have not deactivated the plugin before uploading the new files. The installer can be placed in the activation hook which can check if the plugin had been installed and install if it hadn’t installed already. It can also check to see if it needs to upgrade, in case the user deactivated before uploading the new plugin files or had the plugin deactivated for some other reason.

Any amount of code for which can be moved to the activation and deactivation functions from the init function can save that much overhead and reduce the complexity of the init process.

Activation

function myplugin_activation() {
    $pluginOptions = get_option('myplugin_data');

    if ( false === $pluginOptions ) {
        // Install plugin
    } else if ( MYPLUGIN_VER != $pluginOptions['version'] ) {
        // Upgrade plugin
    }
}

register_activation_hook(__FILE__, 'myplugin_activation');

It is really that easy. WordPress provides a convenience function for hooking into the plugin’s activation hook, no matter where the plugin is located. If your plugin is moved from its directory structure, then if you manually hooked into the activation action, you might not be hooking into the right one. There is a way around that problem, but it is easier to just use register_activation_hook() instead.

Deactivation

The deactivation is easier, but most plugins don’t need it. You can be annoying and prevent the user from disabling your plugin, but they’ll get wise to your deception and remove your plugin, if you choose to do that. It would be unwise to include anything in your plugin that might discourage further usage and users.

It will be useful if you wish to include an uninstaller, in case your plugin creates new tables or adds options or whatever else that may need to be cleaned up. The topic of building an uninstaller is for another day, right now, it is one idea in case you have other needs or ideas for it.

function myplugin_deactivation() {
    $pluginOptions = get_option('myplugin_data');

    if ( true === $pluginOptions['uninstall'] ) {
        delete_option('myplugin_data');
    }
}

register_deactivation_hook(__FILE__, 'myplugin_deactivation');

Again, WordPress provides another convenience function for the deactivation of your plugin. The logic for the deactivation is a lot less than the activation in most cases.

January 8, 2008 Posted by | Writing Plugins Series | , , , | Leave a comment

Writing Plugins: Put all logic in functions

The only code that should be outside functions are the hooks into activate, deactivate, and init hook. A plugin should not assume that it can put HTML and echo blocks outside of functions, because the HTML and logic will display before WordPress is initiated.

The explanation for this is the plugins are included into the process after all of the WordPress library files are included, but before the rest of WordPress is set up. The reason to hook into the ‘init’ hook is that is when WordPress is finished setting everything up and is called at the very end of the wp-setting.php file.

Every plugin should have this code structure:

function mynamespace_init() {
    // hook into all needed filters and actions
}

add_action('init', 'mynamespace_init');

What You Should Never Do

  1. if( WordPress is Setup ) {
        echo "I'm evil
    "; }

    This will always fail, because there is no way to figure out if WordPress is ready for output without using the Plugin API.


  2. require ( ABSPATH . WPINC . '/plugins.php' );

    This will cause WordPress to fail since plugins.php is already included at the time your plugin is included. You should never include WordPress library files! The exception to this might be the admin library files, but you should always check for the function you want before trying to include the file and should always check the inclusion path inside the admin page you’ll be hooking into.

January 7, 2008 Posted by | Writing Plugins Series | , , | 1 Comment

New Documentation causes old Patches to go stale

The issue is that the line numbers will no longer match up and DIFF does not take similar lines in account all of the time. It will on your own system, since it knows what you added and can apply you additions back after it commits other changes from head. Doesn’t always work, but works often enough. The problem with patches is that they are a snapshot and don’t update.

The recent phpdoc style documentation that has been added to a lot of files, will cause a lot of previous patches for those files to go stale. While I believe it is better to have the inline documentation, than to make sure that all patches are able to be committed. I think it does put an burden on those who submitted patches and have to do so again.

I’m potentially sitting on many files which, if they were committed would break almost all of the wp-includes patches. However, if all of my patches were committed, it should only be a one time event.

I just realized this after I had my patches go stale, not from documentation, but from another mass change. I didn’t realize that it had a potential to affect many people people than myself. However, I’m sure documentation will help more people than it will hurt. It shouldn’t be that difficult to resubmit stale patches from old patches. If too much had changed, then the patch was already stale.

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

Codex Documentation for Deprecated Function and File Hooks

I put this together after Peter Westwood announced on his blog about the commit of the deprecated functions and their hooks.

The functions are run for any function that resides in wp-includes/deprecated.php and will not report for any other deprecated function not in that file. There are also two files in wp-includes folder that are deprecated and will give a notice.

Most users won’t notice this however, since the notices won’t be shown unless WP_DEBUG constant exists and is set to true. Most installations and current WordPress versions don’t have that set by default, so the majority of users won’t see anything. Which is stated on the codex page.

I have a problem however with the name of the page and therefore the location. I wish that the name was better, but there is already a page linking to it, so I’m currently too lazy at this point to change the location. I’m also not sure what a better name would be.

It needs more code snippets and I would have added them, but after writing and spending that much time. I decided that placing working or semi-working code snippets would be better left to plugin authors.

To be honest, I didn’t fully agree with the enhancement in the first place. However, the code Westi put in is super sweet and hopefully should allow for further notices to theme and plugin authors that they are using functions or files they should not be using in a future version of their plugin or theme. If a user is interested in whether or not their plugin or theme is using a function or file that may soon disappear and breaking their site, they may follow the instructions to enable WP_DEBUG for WordPress 2.4.

Well, since WordPress 2.4 isn’t released yet, there isn’t much reason for explanation. I suspect more documentation will be written for WordPress 2.4. The current page is just a jump start for any plugin authors who are interested in Peter’s post and want more information. As a co-author of the patch, I was very happy in providing documentation, both source and codex on more information.

As an aside, it is completely possible for a plugin author to also use the functions on their own themes and plugins to allow anyone that might use their code for their own plugin or theme that the function or file is deprecated. The functions are documented as private however, so purists will hate you if you do so.

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

Function Documentation Template

I have a confession. If I could get the function documentation template into WordPress 2.4, then I’ll be super happy. However, I do recognize that doing so would make the documentation super ugly. Who wants to see, “Please document me?” or “This function is undocumented!”

After looking at the current files that have that scattered throughout most of the files, I can say it is better to not have anything than to have that out in the open. “Ha ha, WordPress can’t even get its documentation right!” No, that isn’t it at all.

The purpose of the current patches with the templates is so that others who wish to join in with the documentation effort can have a template for which to fill in the missing pieces. It is all well and good reading the WordPress Inline Documentation page, but really it slows down the process when you have to type all of the text manually.

I know, I did it for most of the taxonomy. I would rather be skinned alive thank you. However I made it through and it had its moments were it was quite fun. At the end, I just figured it was best to just finish it and call it done. The reason for the break was that I didn’t want to short the documentation just because I hated looking at it.

Did I mention I hated writing documentation? I totally do, but I’ve sinned in a past life and I’m looking for redemption. If the pain is a small price to pay, then I’m all for meeting the Programming God with a smile and with examples that I did some good.

Truthfully, if it wasn’t for all of the times I’ve left documentation out of my code, I’ll probably would never had paid any attention to the current plight that exists with the lack of source documentation for functions.

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

Follow

Get every new post delivered to your Inbox.