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.
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.
Taxonomy API Documentation
It would have helped to have read the database table scheme before writing the Taxonomy API documentation. Several really confusing concepts became clear after looking at the table structures for 20 minutes. Looking at the code, it is more like, “WTF? This is some seriously complex code? What does object ID mean?”
The context of it all, well, if I knew what I do now, I probably would have put in some more asides in the documentation. However, I do feel that whatever I would put in the function documentation, could better be placed on the codex for others to correct and modify. The documentation is seriously lacking on the context of how you could use something as complex as the Taxonomy API.
None of the code in the Taxonomy is mine, so I don’t really feel that I have enough karma to write about it at this time. Doesn’t mean I won’t try, just means that I’ll probably be incorrect or vague in a lot of places.
Pretty much in the same situation going over the WordPress Cron API. That is heavy and could seriously use a codex page or two. I’m a little bit more familiar with the Cron API, so the documentation should be better, however I’m not ready to start writing it.
WordPress Documentation Informal and Unofficial Roadmap
Originally appeared on SantosJ.name.
I would totally love it if WordPress had all of its functions documented. It could put WordPress with higher respect with developers. A lot is put on with the Codex, but the Codex is unstructured and doesn’t cover the complete depth of WordPress core and outer edges.
It is true that pieces can be picked up with the codex and trips to the code would allow others to pick up the rest. The WordPress API isn’t as difficult as some applications, so it has done without and flourished without a complete function documentation for a while.
That should change and is changing. However slow, it is quite boring to write documentation and depends on the mood. Realistically, it is very easy to get bored of it after working on it for a few days only to jump back on after taking a break of a few more days.
Documentation Process
For me, the way I’m now writing the documentation is by first going through and adding PHPdoc style documentation to all of the functions and then going back and adding @since information. Well the complete process is as follows.
- Add phpdoc style documentation going down the file to all functions and others that can be documented. Usually just a template which I copy and paste.
- Going back up I add the function name as well as @since
- Going back down I try to add short description information if I can, but definitely the parameters and return type information.
- Going back up I complete as much as possible the long description, but definitely the short description.
- The long description that is still needed, I usually ignore until it either comes to me or I want to finish the documentation for the file.
It might not seem like much, but on average documenting a function can take anywhere from 10 minutes to between 30 minutes and an hour and the more difficult and longer functions.
Old Style Documentation
There have been attempts to document the code before, but the extent is no where near the level of the documentation process. It is likely that because documentation does cause minor overhead to the PHP execution that a lot of documentation would slow WordPress down. However, that should not keep the documentation from the core.
If someone really cared about removing overhead from comments, then they’ll most likely do premature optimization and remove as much white space as possible also and combine as many files as possible. Premature, as the most overhead is likely with the database.
A few projects have noticed an increase and so have a build environment which has the comments, nice format, and split into multiple files and then through the build process compress and combine the files. If someone wanted to squeeze a few milliseconds, then be my guest.
The Roadmap
To me, it would be a pipe dream to think that all the functions in wp-includes would be documented before WordPress 2.4 comes out. However, I would very much like to complete the documentation in the folder before 2.5 comes out. In that way, the core development team can keep up with documentation themselves and the hardest part would be complete.
The team has started to make sure that any new function that goes in gets documentation, which should stop the flow of undocumented functions. However, it would be better if more people offered to help with the documentation. The standard is there and the support is there.
WordPress 2.4 is moving the business logic from the presentation layer in the admin panel backend. Therefore, those functions should also be documented. Hopefully, I hope to also have those done before 2.5 is out also, but going off what I have currently done and how much I have to go to complete wp-includes, I’ll be pushing for WordPress 2.6.
After the Function Documentation
I plan on focusing more on the unit testing and DocBook type documentation. It would be great to get WordPress to the level where has complete unit test coverage of the WordPress functions. Covering regressions, as well as bugs.
It would put WordPress on a higher level with developers, in my opinion, if I know that whatever code I applied went through unit tests to make sure it didn’t cause any regressions and actually fixed problems.
There is someone working on this and since it is supported by Automattic, should be continued without outside help. It would move the test coverage along if more people helped out, because user testing can only pick up so much.
The next step after the unit tests or automated tests, is acceptance testing. Which would automate portions of problems for users and test for common failures.
With an comprehensive WordPress User Guide and Developer Guide written in DocBook markup, it would allow easy access to common answers to users’ and developers’ questions. It would also remove the need to traverse the sometimes difficult to navigate codex. The guides would also be condense enough to provide pin point details instead of trying to describe everything as much as possible. With shorter amount of text, more people will be more willing to actually read through the sections to where they need to go.
WordPress Documentation Plans
The codex is not bad, but it can be improved for both developers and from the work on the user guide and developer guide, long portions should be moved back to the codex to allow for further modification and improvement.
The best thing about the DocBook User and Developer Guides is that they are completely translatable and multiple versions can be available on the same site for those native users. The User and Developer Guides would prevent translators from having to translate the huge amount of text in the codex to provide simple answers.
It is a hope, but there is only so much time. My attempt is basically to jump start the process, so that others that come after me won’t feel as overwhelmed as I do now. To my knowledge and to those that came before me, I believe they also shared my hope. It might have taken one or two years before I came along and put forth a small amount of effort. However, if I don’t get the documentation finished, I believe that some awesome person will come after me and finish what many others have already started.
