Function Documentation

WordPress Function Documentation Progress

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

Getting Involved with Quality Assurance

WordPress is a community effort and it takes everyone in the community to make WordPress the best it needs to be. Getting involved is as easy as using WordPress and reporting when defects show up. It can get up to creating patches for WordPress Trac defects or enhancements. Everyone can do something and people are doing great things for WordPress every day.

Testing WordPress Trunk

If you use just the versions of WordPress that are released, some bugs that you find could have already been fixed on trunk and just awaiting the next release. If you want to really test WordPress, you must first check out the Trunk and join the WP-Testers mailing list.

When testing make sure you input both invalid and valid information and keep in mind what you are expecting what the actual result is. You are trying to break WordPress! If something doesn’t break, then you aren’t trying hard enough or WordPress already has checks which prevent it from breaking.

Reporting Bugs

Reporting bugs is one of the easiest ways to get involved with quality assurance. If a defect is not reported then the WordPress developers and community will not know of the defect. The sooner a defect is reported and confirmed the sooner it can be fixed.

You can report bugs at the WordPress Trac Site. You can also find more information on reporting bugs at the WordPress Codex: Reporting Bugs. As an reminder, you may need to stay around for the life of the ticket to make sure to answer any questions and to follow up on anything that developers or others may need to satisfy the requirements of the report.

Remember: make sure to check the defect or enhancement hasn’t already been fixed or reported. Doing so, will be appreciated by those who have to mark your ticket a duplicate.

Writing Patches

The next step from reporting defects or offering suggestions for enhancements is to provide solutions to existing defects and enhancements. As for most people, you may choose whatever ticket of your ability and liking. You don’t have to start at the top and work your way down.

It should be noted that the tickets of low priority probably won’t be as committed as quickly as those tickets that have a higher priority. Give enough time for the core development team to look over your ticket and see if it worth committing. Keep in touch after you commit the patch to make sure that answer any questions those in the community and core development team may have.

If a reasonable amount of time has past without any resolution with an existing patch, writing another comment asking for a response or set one of the keywords to include ‘dev-feedback’ (without the quotes). It might be that the development team might have forgotten about your ticket. Leaving a friendly reminder might push the ticket ahead in their minds.

When your patch does get committed, rejoice, it will be one less ticket in the queue. Any amount of help is appreciated.

Writing Codex Documentation

The codex is the central place for finding information and help on WordPress. As many features and solutions that WordPress offers, the amount of help is far to broad to be completely covered by any one page or person. If you notice that there is a section that is missing, then sign up and add it.

Writing Inline Documentation

WordPress also needs to have inline or source documentation for those who browse the source for their information. Not everything can be learned from the codex and since the codex can grow outdated, it would be useful to look at the source from time to time. Those that do look at the source need additional information in order to quickly realize what the code is supposed to be doing.

It is also useful for those who can’t read code as clearly as some of those who have been reading and writing code for a long time. In order words, it helps novices of PHP to learn what WordPress is doing. They might not be able to build an application like WordPress, but they can write plugins that are useful for them and/or other people.

There is currently an Inline Documentation Standard that should be used. It is unwise to write a lot for functions since there is a tiny amount of overhead in processing the comments. Not much, but leaving as much detail to only describe what the function does should be enough. Any examples can be located at the codex.

Writing Test Cases

There is currently an Automated Testing Suite for WordPress which you can provide test cases for. Test cases are useful to prove or disprove a defect and whether a patch fixes the defect. Without test cases it would be difficult without manual testing to find out if the defect was fixed. The test cases also can test whether the defect shows up in the future (called a regression).

Writing test cases will be detailed in a later post. Make sure to stay around to learn more!

January 14, 2008 Posted by | Quality Assurance 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