"Documentation by paper"

[Zack Weinberg]

kenner@vlsi1.ultra.nyu.edu (Richard Kenner) writes:

>     You invented MEM_ATTRS and the adjust_address family of functions.
>     There is not one word about these things in doc/*.texi.  
>
> I don't believe they should be there, but they should indeed be *somewhere*.

Are you advocating that there should be no internals manual?  I can
see an argument for "no internals manual is necessary, just use
comments in the code", and I can see an argument for "every internal
interface should at least be mentioned in the internals manual", but
not for some limbo state where there's no way to know if something is
in the manual or not.

>     Write documentation for all this, to the standard you are advocating,
>     and let us see if it's good enough.
>
> Fair enough, though there was stuff added after I did the original work.

Your original patches don't contain much in the way of documentation,
either.

zw