I’m giving this inline documentation project one more week, before I set it on hiatus for a month. I still want to get as much completed before 2.7 is released. I just think that giving the rest of this week should be enough to at least finish the wp-includes directory files. I probably won’t get to the rest of the wp-admin files that have functions. I definitely not going to be able to finish up the wp-admin/includes files with inline documentation.
I’ll be lucky to complete the rest of the files in wp-includes. What I’m doing now is complete the files I know no one else is going to want to complete and then leave the rest to those who want to complete them. There are a couple I think that might be willing to do so.
Next week, I plan on working on plugins and finally complete a few projects that have been on my mind. It will be nice to have those out of my mind as I enter into my year long project.
Well, it might be motivation for the rest of the WordPress community to finish it. I think after working a month on plugins and getting the year long project started, I’ll be fresh to complete the rest of the inline documentation that remains.
It is hard to believe that, after an entire year of starting the inline documentation, with merely two files fully documented or 12% (Ohloh.net), that it is now at 27.7% (Ohloh.net). Well, it is more than that. With the entire WordPress codebase documented, that number should be well within or more than 30%.
It will also mean that WordPress will be at the level of Habari when it comes to inline documentation and beyond Habari when it comes to codex documentation. Well, I could have just worked with Habari and saved myself the trouble and time, but it was worth it. Or at least that is what I tell myself in order to sleep at night.
I think that I’m lucky that those before me put forth the effort to write inline documentation and I hope that those after me continue the effort. Just because a function has inline documentation doesn’t mean that it is complete. Inline documentation, just like the codex documentation has to be maintained. The nice part, is that the maintenance is at the micro level, meaning that when a function changes, only that documentation needs to change also.
One of my fears, is that people will forget that inline documentation needs to be maintained and it will become worthless because of it. My second fear that new functions won’t be documented has been proven to be unfounded. New functions are being documented by most of the core team and it seems that it matters to most of them.
Well, if I had a choice, I would choose incorrect inline documentation, because then it is easier to correct the parts that are wrong. Trying to add new inline documentation is not a task I want to take up again.
Only 9 files remain and after tonight, there should only be 8. After tomorrow, there should only be 7. After that, I’ll work on capabilities.php, comment.php, and widgets.php, which are the more difficult files to document. That will leave category-template.php, link-template.php, post-template.php, and theme.php. I think that with the rest of the week, it isn’t going to be exactly easy completing the *-template.php files.
I’ll be able to complete the functions that have short bodies, but that is only if I can complete the other files before the weekend. I can probably complete a file a day, there is no way I’m going to be able to complete all of the files left. The only good news is that comment.php is halfway complete anyway.
Possibly Related Posts:
- Paying Off Debt Revisited
- Thou Art God
- Saying Good Bye to Dollhouse
- Where the Wild Things Are Movie Review
- Why Choose 1st Financial Bank?
Tags: inline documentation, wordpress