[wp-hackers] Pushing Inline Documentation Patches

[Jacob]

With everything more important going on, I think that phpdoc effort 
should be on the back burner. However, when time is available can these 
issues be addressed? Oh yeah, before I forget, I want to thank you for 
the quick commit of deprecated.php documentation. That was super awesome!

1. Regarding the patch on ticket #4393 and author-template.php 
documentation, I went ahead and added @since information (based off of 
Ozh 
http://planetozh.com/projects/wordpress-functions-history/table_light.html) 
and cleaned up some of the PHPdoc tags. I haven't yet posted the patch, 
since I'm unsure whether I should reopen the old one (#4393) or create a 
new one. I'll most likely create a new ticket.

2. When creating an phpDocumentor site, third party libraries are 
included, which is incorrect behavior. I created a patch that excludes 
the external libraries (see #5443) by using file level phpdoc 
documentation and using a different package name. They will still be 
included, however the functions/classes will no longer be mixed with 
WordPress package functions/classes, which is the correct behavior.

While I'm not sure it wouldn't cause problems, I think it would be an 
advantage to have the patch committed. If and when a WordPress 
phpDocumentor site is created.

3. I made a patch for post.php a long time ago (#3982) based off in part 
the previous patch that was made. As I didn't read too far into the 
ticket discussion, I failed to realize the problems inherit in the first 
patch, which also appears in mine. While I haven't yet gone back over 
the functions and made corrections to the patch, I would be super happy 
if the patch could be committed or some pointers made on how it can get 
to the point where it is ready to be committed.

Also, since it has been a while, I'm not entirely sure the patch will 
commit. If not then, I can create a new patch based off a recent 
repository revision, when I get around to completing and fixing the errors.

4. Dude! Finished the Taxonomy API phpdoc style documentation (#4742). 
It would totally kick ass to close that ticket out.

5. Is there any chance that the phpdoc documentation for wp-settings.php 
(#5211) or wp-includes/vars.php and wp-includes/version.php (also #5211) 
will get in? If not, then would it be wise to close the tickets as 
invalid (the patch for wp-settings.php might be stale anyway since the 
last one is based off of 6311) or won't fix? I would argue that the file 
level documentation makes it worth it for xref sites that include that 
along side the file name, as well as the advantage to phpDocumentor sites.

I basically wrote the documentation for wp-settings.php as a test to see 
what the documentation would look like and practice so that the 
documentation for other files wouldn't suck as much. I think it could be 
useful, as there are a lot of globals and functions (that need to be 
made private) in wp-settings.php that could be referenced in a 
phpdocumentor site. For that reason, I documented vars.php and 
version.php so that when you use @uses $wp_version, phpDocumentor would 
know what you are talking about and reference that global.


Since I'm out of school for the next month, I plan on doing some more 
documentation and hopefully helping with unit tests. After that, 
hopefully someone else will pick up the documentation effort. Which you 
know, there have been people before me, so I can only assume that 
someone will come along after me. Anyone? It is very fun and no, I'm not 
being sarcastic.

-- 

Jacob Santos

http://www.santosj.name - blog
http://wordpress.svn.dragonu.net/unittest/ - unofficial WP unit test suite.

Also known as darkdragon and santosj on WP trac.