svn commit: r211501 - in head/sys: modules modules/send netinet netinet6 sys

[Rui Paulo]

On 21 Aug 2010, at 22:15, Doug Barton wrote:

> On Sat, 21 Aug 2010, Rui Paulo wrote:
> 
>> On 21 Aug 2010, at 19:20, Doug Barton wrote:
>> 
>>> On 08/21/2010 05:07, Rui Paulo wrote:
>>>>> Meanwhile, the fact that in the past code has been committed
>>>>> without man pages is the exact cause of the problem you're
>>>>> describing. It is certainly not a justification for continuing to
>>>>> do it wrong.
>>>> 
>>>> Reverting code just because it doesn't have a man page is pointless.
>>>> Everyone can write the damn man page, but not everyone can write
>>>> code. You should really take this into consideration when proposing a
>>>> commit to be reverted.
>>> 
>>> So let's assume that having lots of code in the tree without a man page is a problem. Further, let's assume that we don't want the problem to get worse. How do you propose that we accomplish that?
>> 
>> By writing man pages...?
> 
> But that's the status quo (I.e., hope that people will/eventually write man pages for stuff) and it hasn't worked so far. The situation isn't actually going to be improved until we make a change. A simple (and I think abundantly reasonable) change that we can make today is, "Don't allow new work to be committed without a man page."
> 
> Meanwhile, there are a lot of benefits to this idea above and beyond the obvious one of having man pages for stuff. The biggest single benefit is that actually writing documentation for things forces you to re-examine assumptions, work through non-obvious and/or non-default code paths, etc. Speaking for myself, it's happened on more than one occasion that as I sit down to document some piece of code I realize that there are either bugs, or at least a better way of doing something. Requiring developers to work through this process before code goes into the tree gets us better code in addition to documentation.

If your concern is to change the status quo, you do understand that you picked the worst possible thread to hijack ? Esp. since the author promised to roll out a man page.

Regards,
--
Rui Paulo