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.
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.
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.