Re: PATCH: Spinlock Documentation

David Fetter <david(at)fetter(dot)org> writes:
> One issue with this patch is that it is not localized. If someone
> goes and changes the S_LOCK implementation for one of the platforms
> below, or adds a new platform, etc., without changing this comment
> too, this comment becomes confusingly obsolete.

Indeed. Moreover, this header comment is supposed to be an overview and
specification of the macros that need to be provided. I think it's an
actively bad idea to clutter it with platform-by-platform details; that
will create a "can't see the forest for the trees" problem.

If we need more info here, I think a comment block before each section
of the file would make more sense. But the patch as provided seems
like it would just be redundant if it were refactored in that form.

What would possibly be useful that's not there now is a paragraph or
two describing the overall layout of the file (eg "gcc then non gcc",
or whatever can be said at more or less that level of detail). But
please don't stick that into the middle of the specification part.

regards, tom lane