[wp-hackers] Inline documentation

[Rich Bowen]

David House wrote:
> On 16/02/06, Mark Jaquith <mark.wordpress at txfx.net> wrote:
>> We could work on patches amongst ourselves, and then when we think
>> they're ready to go we could have 2 or 3 people sign off on it and
>> send it off with a "commit" tag.
> 
> That's what bug gardeners are for, right? :)
> 
> I'll bg|commit any of these patches as long as the commenting isn't
> overboard. My personal commenting policy is one line before each
> function (plus other places within the function, but I think we are
> mainly deailing with the former type in this thread). If the
> parameters names aren't self explanatory, then perhaps a short
> sentence explaining their purpose, but nothing > 3 lines in total.

I fail to see any value to such a limit. The entire purpose of doing is
is so that there is inline API documentation. That requires, at a
miminum, a description of the argument(s) and the return value(s).
Forcing an arbitrary line number limit on that is artificial and
unnecessary.

-- 
Rich Bowen
rbowen at rcbowen.com