Re: [RESEND][PATCH] Add /proc/mempool to display mempool usage

[Michael Kerrisk]

On Mon, Dec 1, 2008 at 9:54 PM, Linus Torvalds
<torvalds@xxxxxxxxxxxxxxxxxxxx> wrote:
>
>
> On Tue, 2 Dec 2008, Pekka Enberg wrote:
>>
>> OK, but why do we have those different ABI "stages" in
>> Documentation/ABI then? The README file there seems to contradict what
>> you say. Or maybe I'm reading it wrong...
>
> I think that whole Documentation/ABI stuff is utter tosh, and should just
> be thrown out, whenever it talks about interfaces that are _not_ ABI's.
>
> IOW, it's fine to document things that are actually supposed to be stable,
> but:
>
>  - assuming that non-documentation means that it's not an ABI is bogus
>   and wrong.

Agreed.  (When so much is much is undocumented anyway, there is no way
that lack of documentation can be used to signal "this is not an ABI.)

>  - explicitly documenting something as "not an ABI" is wrongheaded and
>   stupid, because it's meaningless and only sets people up for being
>   disappointed later.

Agreed.

[...]

> Finally, when it comes to documentation as a bigger issue:
>
>  - wrong documentation is irrelevant. It doesn't matter if the
>   documentation says "X", when the code does "Y".
>
>   If people rely on "Y", then pointing at the docs and saying "but you
>   should never have relied on it, because teh docs say X" is totally and
>   utterly bogus. The _documentation_ was wrong. Don't ever use incorrect
>   documentation as an excuse.

Agreed.

> Too many people seem to think that documentation is the "final" argument.
> It's not. Not even close. It's a hint and a help, but it's _secondary_ to
> code. Anybody who doesn't understand that should never be allowed to write
> code (or documentation, for that matte).

While clearly documentation is not the final answer, I think you
undervalue it somewhat, and I think it's worth mentioning two specific
points.  Documentation may be secondary to code, but it can help a
lot, especially if:

* The documentation is done at the same time as the code (by the
developer, or by someone working with the developer).  This typically
makes the developer think more about the code they are writing.  It
also gives others to more quickly understand the code with the aim of
reviewing the code and/or API design, and perhaps testing it.  There
simply isn't enough review and testing going on, and documentation can
make a real difference there, IMO.

*  While the "but you should never have relied on it, because the docs
say X" argument may not hold, there is one important way that I think
documentation can still help: explicitly saying that "the behavior is
unspecified around point X, and other code should not rely on a
specific behavior".  This legitimately allows developers to change the
behavior around point X in the future.  (I made the point at LPC, if
you force users to read the code behind an API, then you end up
creating a "tight spec", since they will do exactly what the code
permits.  In this sense, documentation can be used to "loosen" the
spec.)

Cheers,

Michael




-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git
man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html
Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/