Function Documentation

WordPress Function Documentation Progress

Speaking at WordCamp Dallas 2008

My talk has been accepted for inclusion on Sunday, March 30. The nice part is that if perhaps I stumble, enough people will be able to leave since I have the last session of the day. I have some experience speaking in front of people I’ve never seen before in my life, but I every time I stand in front of a crowd I think of two things. The first, is that I think I’ll kick major ass and I almost never do and the second that I’m nervous as hell. If I don’t wet myself in the first 10 minutes, then I think it’ll go great.

The talk is titled “Testing with WordPress” but is on automated testing and why developers should be helping out with the effort. I think it will be split into two parts, the first will be what automated testing is and why you should help out with the effort and the second part will be all code and showing how to help with the effort. It is fairly simple presentation, but I assume that powerpoint is an option.

I just have to practice and write enough test cases to present enough material for 30 minutes. I also have a project that I have to finish in order to reveal its purpose during the presentation. Actually, I plan on revealing the project sooner and still using the project during the session. It should be interesting to say the least, as it will be both my first conference, first WordCamp, and first time I’ll be talking in front of a large crowd.

Should be fun. WordCamp Dallas I mean. I’m still debating, whether I’ll be going to the WordCamp 2008 in San Francisco. I won’t be speaking there, but I think it would be nice to see the place and arrive a couple of days early to enjoy the sights and visit family. I’m only going to WordCamp 2008, if I have enough money to fly down there, but It is only a 7 hour drive to Frisco. In the worse case, I’ll be driving down to Frisco Friday after work, arrive around midnight, check into my hotel and crash, and arrive for the first day of sessions.

I plan on taking a lot of pictures, but I’m unsure if I’m going to rant at any point about WordPress. I hope not, because I enjoy living and dissing WordPress at an event strictly WordPress doesn’t seem like the most logical move, if you enjoyed breathing. I rant a lot, so I have to watch myself, both during my talk and during the other talks. I’m pretty mellow in person, so I doubt I’ll get into any trouble.

I’ll probably be the least well known person at the sessions, so I doubt anyone is going to say anything about what I’ve done with WordPress. I don’t intend on discussing what I’ve done with WordPress, unless someone asks. I’ll just be that guy who takes a lot of pictures and then bam, I’ll be speaking at the end of the day. All in all, it will be totally awesome and I look forward to giving my viewpoint out there.


February 1, 2008 Posted by | WordPress | | 2 Comments

Protected: Talk Draft

This content is password protected. To view it please enter your password below:

January 18, 2008 Posted by | WordPress | Enter your password to view comments.

Roadmap of WP-Includes Inline Documentation

A followup to the earlier post on unfinished functions to write how I’m going to document the files based off of the information in that post.

Finished Files

These files have been finished since the last post. There are only 18 more files to complete before the entire wp-includes folder is documented!

  1. l10n.php
  2. pluggable.php
  3. kses.php
  4. locale.php

Must Finish Before WordPress 2.5

I want to get these done as soon as possible and at least before WordPress 2.5 is released. Not sure if any of these files will be done in any particular order as listed. Probably just whatever falls in this list and that I feel like documenting.

  1. user.php (9 functions left)
  2. comment.php (Already started: 20 functions left)
  3. cron.php (also need a post on how to use it. 13 functions left)
  4. category.php (15 functions left)
  5. script-loader.php
  6. feed.php
  7. wpdb.php (10 functions left. File has incomplete new methods which require documentation.)

Must Finish Before WordPress 2.6

If I can’t get finish these before WordPress 2.5, then I hope to get them in before WordPress 2.6. Probably doing a lot of work during the Summer. It will be cutting the work close to the deadline for getting these in to WordPress 2.6, if I wait until last half of May.

  1. category-template.php
  2. capabilities.php
  3. query.php
  4. post-template.php
  5. link-template.php
  6. post.php (not everything perhaps, but a lot more finished, it is already started)

Must Finish Before WordPress 2.7

These will probably be finished either before WordPress 2.6 or during the time that the WordPress wp-admin/includes files are started to be documented. These are long files with a lot of documented functions and elements. They will take many hours to document each, so they’ll most likely be worked on over the course of an entire version.

There aren’t that many files and hopefully the functions when they are finished will be committed. In that way, at least some of the work will benefit users while the work is continued. It is the way that the taxonomy.php file was handled and it took quite a while to document that file (not because of time but because of motivation).

  1. formatting.php
  2. functions.php
  3. general-template.php
  4. post.php
  5. theme.php
  6. widgets.php
  7. classes.php

After the wp-includes folder is finished with complete inline documentation, it will be time to work on wp-admin/includes/, and perhaps the rest of the wp-admin folder for as many inline documentation worthy items as possible. After that, it will be time to help with the effort to write test cases for the WordPress library to ensure quality.

As an Aside

I hope to continue the Developer Manual work for as long as possible leading up to WordPress 2.5 and beyond to WordPress 2.6. Eventually, at some point I’m going to have to write some User Manual posts to eventually add to the codex. After that, I’ll have to package everything up and post the full contents of those posts to the codex for everyone else to edit and enjoy.

At my current rate, I should have a lot of content before WordPress 2.5 is completed. I should note that I don’t feel obligated to post every day and since I have school now, if I can’t write enough posts on the weekends, there will be times when I won’t have enough posts to last until the next weekend. Usually, I just drain all of the information from my head until I have nothing left.

Until next time, I hope you enjoy reading the rest of my posts!

January 17, 2008 Posted by | WordPress | , | 1 Comment

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

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

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

WordPress Ohloh Comments Ratio Raises to 18%

The inclusions of comments into the core of WordPress has risen the ratio from around 12% to 18% and the goal should be to get that passed 26%, the minimal margin they have for most projects.

However, while the primary focus that I have is phpdoc style comments and documentation, it remains that writing other inline comments would move that percentage even higher. It seems that since the author of said code knows what it does, it is assumed that others can look at it and figure it out. That isn’t always the case with beginners.

I suppose my rule is that since I don’t understand JavaScript code that well, I write comments that is more explaining the what I’m doing to myself, more than explaining it to someone else. When I go back to the code, I want to know what it does, so that I don’t have to spend time figuring out my own code.

It could explain why inline documentation inside of functions is almost nonexistent. Granted, once the phpdoc style comments are finished, a grassroots effort could be made for writing inline comments for inside the functions. However, I rather think the codex does a better job of explaining matters.

January 6, 2008 Posted by | WordPress | , , , , | Leave a 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

Amount of Unfinished functions in WordPress Files

The list only includes the unfinished files in the wp-includes folder. On deciding which files to do first, I think finishing the ones with shorter list of unfinished functions helps. When people dive into the source, I want them to view as many files with comments as possible to know that the effort is on going.

  • capabilities.php

    5 functions.
    5 properties.
    26 methods.
    3 classes.

  • category.php – 16 functions.
  • category-template.php – 21 functions.
  • classes.php – Mostly methods, properties, and classes. Will do as one of the last files to complete.
  • comment.php – 32 functions.
  • cron.php

    13 functions.

    The API will be difficult to document given the complexity of how the functions are used. However, this will raise the priority since the Cron API is one of the little known API and any help would be beneficial to confused users. I’ll also most likely post a tutorial once I’ve finished documenting the functions.

  • feed.php – 20 functions.
  • formatting.php

    54 functions.

    Given the amount of functions it will most likely be worked on in stages, much like the taxonomy API was. However, most of the functions will only need short descriptions which will decrease the amount of time needed to fully document the code. The longest and most difficult parts of documentation is the long descriptions.

  • functions.php

    80 functions.

    Again, one of the largest files with a lot of functions. It has functions which will be a little bit more difficult to do and a lot of trac patches are against that file, so it would break a lot of current patches to document the file. The comment for formatting.php also applies to this file.

    Some functions are already documented, so the count is actually lower.

  • general-template.php

    48 functions.

    Most of the functions only require short descriptions so the file will most likely be done in stages with the functions which only require short descriptions being done first. Then moving on to the harder and lesser amount of functions needing long descriptions.

  • l10n.php – 10 functions.
  • link-template.php – 38 functions.
  • locale.php

    10 methods.

    1 class.
    8 properties.

  • pluggable.php – 35 functions.
  • post.php – 71 functions.
  • post-template.php – 27 functions.
  • query.php –
  • script-loader.php

    13 methods.
    11 properties.
    6 functions.
    2 classes.

  • theme.php – 41 functions.
  • user.php – 12 functions.
  • widgets.php – 54 functions.

January 4, 2008 Posted by | WordPress | 1 Comment