[wp-hackers] Pushing Inline Documentation Patches
wordpress at santosj.name
Fri Dec 14 00:22:49 GMT 2007
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
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
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.
More information about the wp-hackers