[wp-hackers] Inline documentation

[Rich Bowen]

David House wrote:
> On 17/02/06, Carthik Sharma <carthik at gmail.com> wrote:
>> Digressing from the main topic here:
>> David, some of the "Doesn't seem to do anything" params (like `all`
>> and `optionall`) are actually supposed to do stuff , and they did,
>> prior to a commit that broke that functionality. I suppose that is a
>> bug, then.
>> http://comox.textdrive.com/pipermail/wp-docs/2006-January/001232.html
>> is where I wrote up about this recently.
> 
> Okay, but it's still important to document them accurately. Just lying
> in the documentation to cover up a bug won't help anyone trying to use
> the function then desperately trying to figure out why a given
> parameter doesn't work...

This is somewhere that I would disagree. The documentation should
document the API, and the function should implement the API. If the
function is broken, this can be noted, but it is the job of the function
to implement the API, not of the API to document the function.

The XP perspective on this is that the documentation should be written
first, and then the code should be written that implements the
documentation. Obviously, it's a little late for that, but it's still
the right concept to keep in mind.

-- 
Rich Bowen
rbowen at rcbowen.com