Documenting WordPress
As I mentioned in my last WordPress post I’ve been working on adding documentation to the core of WordPress, specifically the formatting.php file. This is quite a big file will upwards of 2000 lines of code and around 65 functions to document. It is used extensively in the formatting of pretty much every aspect of a blog. It surprised me therefore that when I started getting involved in developing WordPress this file (with the exception of may a dozen functions) completely lacked documentation.
Over the past number of weeks I’ve been (rather slowly, it’s quite a boring process) adding inline documentation to the file. So far I’ve got around 70-80% of the file done and plan on doing as much of the rest that I can. Unfortunately some of the functions are a bit difficult for me to understand and, at the risk of writing totally incorrect documentation, I’ve been leaving these.
However there is only one other developer actively documenting the code. New code is being documented as it is written but there is a great deal of code lacking any. Hopefully the 2.7 release will see a good deal more added. My contributions have already been committed to the Subversion trunk which I’m quite happy about.
Yeah, I was looking over what you wrote. There are a lot of functions I don’t understand either, which is why I’ve hold off on documenting them. There are other files, which I’m not looking forward to documenting also. The classes.php and cababilities.php files are going to be a pain and I’m not quite up to that much torture at the moment.
I just finished post.php and I think I’m going to take a break after I finish the script-loader.php. I documented all, but a few I think.
I do think that after formatting.php is finished, the effort could end right then and most people will have everything they need to build plugins and themes. However, I’m looking to complete all of the files and functions.
I thank you for joining the effort. I’ve added your handle to the WordPress Codex Inline Documentation page. However, you can add your real name. That is pretty much the full amount of people who have and had worked on the inline documentation.
Man it’s crazy that your name is appearing on the Wordpress Codex AND that your code was also used in the latest update (2.6.1). That’s insane! Well done, Scott.
I just wanted to leave a positive feedback for Scott. He had helped me with a wordpress issue on Mirc. I had been working on some code for 3 days to get working and I ran into a snag. Scott helped me get it working the “correct” way. He was fast, and very nice to work with. He is a wordpress god!
Thanks again Scott!
I completed formatting.php today. I was wondering if you completed any more and wanted to add more inline documentation to the file before the ticket is closed out.
I’m hoping you will continue with the effort. There are many template tags (functions in *-template.php files) that need to be documented. It should be pretty easy and go pretty quick.
I still hope to have all of the inline documentation finished for WordPress 2.7. I thank you for your help, it means a lot.
Think I finished as much as I could on formatting.php, thanks for reading it over and fixing things.
I’ll have a look at the template files in the next few days as they are pretty commonly used and I would love to get them documented for 2.7. Not sure how much I’ll get done but every little helps.
I’m noticing that some of the files I have do have finished functions with inline documentation. I’m going to go over them and create a patch and create new tickets for some of the other files.
It seems I documented query.php some time ago, but never finished it. I’m going to create a patch for that.
Thank you for posting this…