[wp-hackers] PHPDoc and state of the Codex

[Adam Hunter]

I wasn't thinking that the codex was going to be removed.  My suggestion
would be to turn the function reference into example based pages.  Not every
function will need to be documented their either.  Something along the lines
of this: http://framework.zend.com/manual/en/is what I am thinking.  Granted
the Zend Framework is entirely class based, almost every public function has
an example of how to use it.

For example, when I first started using the Zend Framework, I mainly looked
through the reference guide to find out what to use and where/how to use it.
 As I gained experience in using the Zend Framework, I began migrating my
research to the PHPDoc information, because I once I understood the
functions and what they did, I needed more specific technical information on
them.

While maintaining the function reference will definitely be a bear, I think
using the PHPDoc for reference, writing the function reference as a more
comprehensive guide will be easier, because looking up function specs will
be significantly easier.  Also, there are functions that will almost never
change, making sure all of them have complete documentation and examples
would be a good starting point.  Many of them do, such as wpdb.  I would be
happy to help complete the function reference in this fashion.

Also, is there a way to specifically trac phpDoc updates through SVN?  It
would be a nice starting point to be alerted if a function has changed.
 Sorry all for the lengthy email.

Thanks,
Adam