Re: libobjc: header cleanup for new API (11)

[Nicola Pero]

>> This patch just updates comments in objc/message.h and objc/runtime.h.
>
> I think at some point, it would be nice to have a document for this all,
> but I don't like the current situation wrt documentation, so I hate to
> even suggest it.  :-(.  An abi reference generated from source might work.

Yes.  Suggestions are welcome.

At this stage, the (Modern) GNU Objective-C Runtime API is documented in the header
files; objc/objc.h, objc/runtime.h and objc/message.h.  I like writing documentation
and I documented quite a lot - each function, type, etc. :-)

I added a section in the GCC manual about what the headers are and an explanation that
the API is documented in the headers.  It would be better to have the function/API reference
in the manual itself, but we'd need to sort out how to generate documentation for the manual
from the headers (I wouldn't want to move the reference documentation too far away
from the code otherwise they tend to get out of sync). ;-)

-

The ABI instead is not really documented anywhere; for GCC 4.7 I'd like to have an ABI
document that documents the GNU Objective-C Runtime ABI, at least the "Modern"
one, ie, the new ABI that I'd like to work on in 4.7 (assuming I get the time
to do it).  (by "Objective-C ABI" I mean a description of how the various
Objective-C constructs are compiled, and a description of the module structure
that is passed by the compiler to the runtime for each compilation unit).

I don't expect the ABI document to be very long, probably 5 to 10 pages,
so it may fit well in the GCC manual itself, but other suggestions are welcome.

Thanks