[wp-hackers] Inline documentation

[Sean Hickey]

Howdy,
  As a WP plugin developer I've been dying for something like this for
a long time.  The codex is painfully lacking in API documentation. 
It's real bad.  The benefit of using DocBlocks is having something
like phpDocumentor do all the API documentation for you.

  While the codex might be fine for casual developers, something like
auto generated API documentation would be a God send for more serious
developers.  Heck, half the packages in the Pear repository don't even
have standard documentation, just the auto generated docs created by
phpDocumentor.  The reason is, that's enough for someone who knows
what they're doing.

  The generated documentation is HTML, it can be added to the search
on wordpress.org, and it will be indexed by search engines.

  Anyone here who doesn't want to use @param and @return might not
understand what those tags meant for.  They don't do anything, and
aren't meant to be human readable.  They are meant for parsers like
phpDocumentor.  Without them the generated API documentation would be
worthless.

  Regardless of what is decided, the WordPress code needs inline
documentation in a bad way.  Some of the developers should be ashamed
of themselves for the lack of commenting.  One of the first rules of
programming is comment, and comment often.  There's no real excuse for
skipping comments.

  If you guys decide to push forward with the DocBlock style of
commenting, I'd be more than happy to help.

- Sean H.