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:
- Bullet: E-Book Library Management and Content Server
- Using ZendFramework 2 beta1 For Directory Project
- The Way of Kings and Cosmere Theory
- “In Time” Movie Premise Flawed
- Completing HTTP Library For PHP
I applaud your efforts. As a developer coming to wordpress interested in how it works, I was amazed at the lack of documentation in the code. I’m still getting my bearings but if you’ve got anything specific that you’d like help on, feel free to ask. I can’t think of a better way of learning the code than by documenting it.
Well, I’m having difficult finding time for post.php, which much of the inline documentation is inaccurate, which is worse than not having any.
Function.php has half of the functions documented and is arguably the most used functions in WordPress besides formatting.php, which probably is the most used or close second.
I jump around a lot, so I’m not sure what I’ll be working on. My advice is always, if you see a function that you’ve discovered the meaning behind, then write documentation for it and apply a patch to http://trac.wordpress.org/ticket/7038 or if you document an entire file, search for a ticket for that file or if one doesn’t exist then create one for it.
I’ve been devoting about an hour each Saturday and Sunday to completing the inline documentation. I plan on completing the script loader.php and shortcodes.php files today. I also want to revisit some of the functions in post.php and try to fix the documentation for some of the functions. I’m probably not going to revisit functions.php or formatting.php until post.php is completed.
Also, if you document an entire file, then add your name to the list on the list of contributors for the inline documentation effort.
Hey, I’ve kinda jumped in and had a go on formatting.php, expanding on your diff from trac. I’ve only done the first few functions at the moment but I was wondering if you’d mind checking them and pointing out anything I forgot or could’ve done better. The diff is here.
Cheers.
I think it looks good, except that the “function_name() -” standard has been removed since it doesn’t look right in phpdocumentor and phpxref sites.
I wouldn’t worry about critique, if something is wrong, someone will come along and fix it.