[wp-hackers] Inline documentation

[David House]

On 20/02/06, Ryan Boren <ryan at boren.nu> wrote:
> They have a
> shelf-life of about two weeks after which they are hopelessly
> out-of-date due to the neglect and colossal indifference that follows
> the breathy flush of the original eagerness to document everything inline.

Keep in mind we're not documenting every nook and cranny of every
function: just their parameters and their return values. If you change
the paramters of functions (read: changing the API), then something's
seriously wrong. I doubt we're breaking plugins every two weeks ;)

My main point for including the docs is: why not? Isn't doesn't bloat
the runtime for WP. The devs don't have to do anything other than 'svn
ci'. If we followed this docs-person-with-commit-access idea, then you
wouldn't have to do anything at all. It helps:

1) People developing with ZDE, Eclipse and other IDEs that support
javadoc/phpdoc style comments.
2) People who are learning the WP codebase. We could use phpDocumentor
or something to generate a nice HTML API docs. If we used the codex
then we'd have to invest man hours in copying information from one to
the other, so the choices are basically keep it just in the codex or
keep it both in the core and in HTML format. We also have at least
three files now fully or nearly fully documented, whereas the codex
Function_Reference contains just a handful of functions.
3) Even people who are familiar with the codebase that feel like
reading a six-line comment in english instead of reading a thirty line
function in code. It's a lot quicker to read someone else's
description than to read through the code.

--
-David House, dmhouse at gmail.com, http://xmouse.ithium.net