Finishing WP-Admin Directory Inline Documentation

Posted by Jacob Santos on August 12, 2008

I should had noted that most of the files in wp-admin WordPress directory only require file level inline documentation. That allows for large portions of the directory to be finished quickly. I’ve also noted that many of the files in the wp-admin/includes directory only have a few functions.

I think my focus now has switched to focusing on the wp-admin files and finishing those files up as soon as possible. If the goal is to have all of the Inline Documentation finished by 2.7, knocking the wp-includes directory out will allow just the wp-includes directory to remain.

Well, there are other files both in wp-admin and wp-includes directories that will require inline documentation, but they aren’t important to plugin developers. Most of them will only need file and, or class level inline documentation in order to put the classes and functions in the right package.

These files are hopefully have completed by the end of the month and complete all of the file level inline documentation by the end of the week. Many of these files can be finished in one sitting. It will leave 8 WordPress files and about 6 to 8 external library files left over to be documented.

  1. bookmark.php – 9 functions
  2. comment.php – 5 functions
  3. dashboard.php – 13 functions
  4. export.php – 9 functions
  5. image.php – 11 functions
  6. import.php – 4 functions
  7. misc.php – 9 functions
  8. schema.php – 8 functions
  9. taxonomy.php – 10 functions
  10. theme.php – 3 functions
  11. update-core.php – 1 function
  12. update.php – 6 functions
  13. widgets.php – 5 functions

I think it will feel great to have so many files in the base, wp-admin, and wp-includes directories to be documented. Already many of the new functions already have inline documentation going in and once the inline documentation is completed for all of the files, it won’t be difficult to keep on top of the functions going in.

The wp-includes directory files that I want to finish by the end of the month are below. This will get rid of the short files, which should be quick enough to document. Much like the wp-admin/includes files, the amount of time depends on how many functions, but also on the length of the functions. It is quicker to document 20 functions that only require short descriptions, than 10 functions, which require both short and long descriptions. This also means that many of the “harder” files, which really are a lot of shorter functions shouldn’t take very long.

  1. cron.php – 13 functions
  2. media.php – 16 functions
  3. script-loader.php – 5 functions
  4. user.php – 13 functions

The main focus of inline documentation after all of these files are finished is post.php, which is grossly inaccurate and needs to be corrected, once and for all. Functions.php has been completed and aside from formatting.php, a lot of the more used files are starting to be worked on and completed.

It will go a long way to having a lot of the functions and files with inline documentation. The focus can then turn to the WordPress test suite, which needs help completing and the Codex. I plan on writing an user and developer manual at some point and these will help in being able to write comprehensive and concise information for the manuals.

Possibly Related Posts:


General

1 Comments.

Trackbacks and Pingbacks: