Tag Archives: inline documentation

One More Week of Inline Documentation

Posted by Jacob Santos on September 15, 2008 Comments Off

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:


More Inline Documentation Completed

Posted by Jacob Santos on August 30, 2008 Comments Off

A lot of inline documentation has gone into WordPress 2.7 today. The file script-loader.php has been completed and is one of the more easy files to complete. The file formatting.php is also completed, but is awaiting commit to the WordPress Trunk. Thanks to Scott Houston for helping with the formatting.php file, documenting over 90% of the file.

Now that post.php, functions.php, and now formatting.php are finished, that remains are only 14 files. There are 5 files that deal with “template tags” that have mostly short function bodies that will really easy and quick to document. There are still three “easy” files that need to be documented. There are at least two files that I’m not even going to touch until the end.

I hope to complete more of the template files, so that theme developers can reference that documentation. Hopefully, the idea for adding phpDocumentor or PHPXref site to wordpress.org subdomain will go through before WordPress 2.7 is out, so that people can reference it. It would be better to reference a wordpress.org site for on the Codex and other sites, because you can be sure that it will be up.

It looks like my personal goal of having the inline documentation finished might just come to pass. There should be enough time to complete the inline documentation by October / November release date (historically, WordPress developers try to release a month early).

Possibly Related Posts:


Documenting the Easy Functions First

Posted by Jacob Santos on June 16, 2008 5 comments

I think my mindset has shifted somewhat. Before it was get as many shorter files as possible out of the way and then focus on the files which have the most functions in them. I’m thinking this isn’t the best way to go about writing the inline documentation.

Mostly, the inline documentation for post.php is incorrect. Some parts are horrible and completely inaccurate. That said, most of the functions are documented, albeit inaccurately. It begs the question whether it is better to have poorly written documentation, than no documentation at all. It isn’t something I can answer, because if the answer is no, then I really shouldn’t be writing inline documentation or any documentation for that matter.

The goal is to have inline documentation which is as accurate as possible and as reflective of the code as possible. I think practice makes perfect, but I still have a long way to go.

I documented about half of the functions in functions.php (some of the total was from documentation that was already there, or added by someone else). There are still some functions which are short in the amount of lines of code. Those functions could do with a descriptive short description header with the parameters and return type documented. Not hard work at all.

That said, by the time those functions are finished, most of the file is finished and it shouldn’t be that difficult to finish the file off. Completing functions.php and formatting.php would be a huge benefit towards the inline documentation effort. Many of the functions plugin and them authors will use will be found in those two files. The post.php file and/or post-template.php file also contains a lot of functions within.

I think my goal now has shifted to completing the files which are almost complete. Still have to finish category.php, but that can wait. I think fixing post.php and finishing it will also be helpful for those writing themes and plugins. It is coming down to what is left is what most plugin and theme authors use the most. This should be a huge turning point towards the quality of documentation.

The next step after the inline documentation is finished is to turn towards the codex and translate the geek speak to non-technical explanations and examples to help theme and plugin authors further. For me, that will probably come during Spring of 2009. If I can finish up the inline documentation for Summer of 2008, then I’ll be working on a few other projects for the Fall.

Possibly Related Posts: