* Bartlomiej Zolnierkiewicz <[EMAIL PROTECTED]> wrote:
> > no. These are not DocBook comments, if you look carefully at the
> > format [it's not a leading '/**' comment block]. But obviously
> > documenting this in the include file is very useful, because that's
> > where people look first, so i kept it. (the APIs will not deviate
> > across architectures)
>
> comments and variable names in include files have a tendency for going
> out-of-sync in the long term so IMO having a DocBook to point people
> at would be a better solution (+ it would shrink <linux/kgdb.h> by 122
> lines)
yes, i very much agree in general, but this is a _SPECIAL CASE_, and i
already tried to point that out to Christoph but he's not the type of
guy who listens to others all that easily when it comes to his pet
peeves ;-)
this is a special case because it's an _architecture facility_.
read: right now we have 25 architectures, and this means that in a year
we'll have 25 arch/*/kernel/kgdb.c files. What will be more likely to
get out of sync, 25 full sets of DocBook entries of the same thing,
spread across 25 architectures - or that lone single
include/linux/kgdb.h file that is looked at by everyone? And what will
be easier to update if we extend any of the APIs?
so the DocBook rules are fine, but in this SPECIAL CASE they cause the
possibly worst solution: total information anarchy!
the correct approach is to put the _arch specific_ details into the
arch/*/kernel/kgdb.c files, and to keep the generic bits in
include/linux/kgdb.h. KGDB did exactly that and it's by far the cleanest
and most maintainable approach.
If DocBook does not pick that up then it's a _DocBook problem_. I dont
mind adding some dummy weak aliases to kernel/kgdb.c for DocBook to pick
up, to help solve this DocBook problem - but to blame it on KGDB is way
off the mark. It used to be the crappiest piece of sh*t everyone would
laugh about when looking at (right before suffering permanent brain
damage), but now it's one of the cleanest and most CodingStyle conform
kernel subsystems :-)
case in point:
errors lines of code errors/KLOC
kernel/kgdb.c 0 1839 0
fs/xfs/ 2102 106019 19.8
right, XFS has more than 2 thousand bona fide CodingStyle violations!
But yeah, it has the luxory of upstream integration ... ;-)
[ not that i want to pick on XFS - it's a very clean codebase in my
opinion, considering its fundamental complexity. It's just that anyone
who wants to find a style error in KGDB now has to search _hard_ ;-) ]
Ingo
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
