Re: Yet more ARM breakage in linux-next

[Randy Dunlap <randy.dunlap@oracle.com>]

David Miller wrote:
> From: Randy Dunlap <randy.dunlap@oracle.com>
> Date: Wed, 03 Dec 2008 15:37:44 -0800
> 
>> Rusty Russell wrote:
>>> On Thursday 04 December 2008 07:11:09 Andrew Morton wrote:
>>>> On Wed, 3 Dec 2008 19:29:05 +0000
>>>>
>>>> Russell King <rmk+lkml@arm.linux.org.uk> wrote:
>>>>> This seems to be causing lots of ARM breakage:
>>>>>
>>>>> lib/find_next_bit.c:183: error: implicit declaration of function '__fls'
>>>>>
>>>>> Whoever's responsible,
>>>> git-blame?
>>> It's me.  Turns out sparc, avr32 and arm all don't define __fls in their
>>> asm/bitops.h, and I'm the first one to use it in generic code.
>>>
>>> But as I prepared this patch, I note that the armv5 __fls/fls is wrong:
>>>
>>>   /* Implement fls() in C so that 64-bit args are suitably truncated */
>>>   static inline int fls(int x)
>>>   {
>>>       return __fls(x);
>>>   }
>>>
>>> __fls(x) returns a bit number (0-31).  fls() returns 0 or bitnumber+1.
>>>
>>> (Yes, classic useless kerneldoc documentation doesn't actually *say* 
>>> this clearly).
>>  
>> oh fud.  That's not a fault of kernel-doc, just of whoever wrote it.
>> It's only as good as someone makes it.
> 
> That's true, but it is not fud to say that kerneldoc is only any good
> if people keep it accurate and up to date, and this is what I think
> Rusty is upset about.
> 
> I personally don't like kerneldoc at all, because the truth is that
> people will work on fixing bugs and other userful things before
> keeping kerneldoc up to date.
> 
> And that's the basic fact which cannot be denied.
> 
> I wish it could work, but it doesn't across the board.  So unless
> we have dedicated monkeys scouring over every single patch that
> goes into the tree and doing the necessary kerneldoc updates,
> kerneldoc will be chronically wrong somewhere.
> 
> That leads to confusion and lost developer time.  Because if the
> kerneldoc bits are wrong, it's worthless.

That's all independent of kernel-doc.  I.e., if someone just used
plain comments and they still were not being updated (typical),
then it's the same problem.  And yes, I agree, the wrong documentation
is bad and a time sink.

~Randy