Re: "Documentation by paper"

[Phil Edwards <phil at codesourcery dot com>]

Richard Kenner wrote:
>     I certainly never called it that.  I certainly don't dispute the need
>     for writing down what you're asking for.  But we also need useful API
>     catalogs:
>
> But these aren't libraries that have APIs.  Instead, they are a
> collection of functions that implement a compiler.

How many times has this list seen an email asking, "I need to do thus-and-so,
do we have a function for that?"  I've asked it myself.  Yes, we could go
read every header file and hope.  I find a list of APIs far more handy and
far more accessible.

You're also ignoring the fact that we don't need to be a libfoo.a in order to
have an exported API.  "Functions to work with GIMPLE" would be an excellent
module to have listed, for example.  It certainly has an API.  The last summit
pointed out that GCC has nothing approaching a modular interface; everything
knows about everything else.  Claiming that internal blocks of code don't have
APIs is an excellent step towards preserving the mish-mash state.


> I'm not convinced having a printed cross-reference (or one in a format
> related to printing) is useful.  I don't see what benefit they have that
> a tags file does not.  Can you explain that?

...the heck?  You read tags file with your bare eyes, then?  I think I'm done
with this conversation.

Kenner, nobody is arguing against having a high-level documentation overview.
Everybody agrees that it's a great idea.  Please, write one.  Those of us who
cannot keep the source code in our heads use these crutches like API listings
and cross-reference tools.  One is not a replacement for the other.