Re: Yet more ARM breakage in linux-next

[David Miller <davem@davemloft.net>]

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.