objective-c @compatibility_alias construct documented

[Nicola Pero <n dot pero at mi dot flashnet dot it>]

Hi, 

while looking at the Objective-C parser code I found out it accepts this
construct -

@compatibility_alias ClassA ClassB;

which I have never seen documented anywhere - I completely ignored about
its existence - and so I think do most Objective-C developers.

Anyway - I tested it and it works :-) - and probably could be useful in
some particular situations - so here is a patch for
gcc/libobjc/objc-features.texi to document this forgotten feature of the
Objective-C compiler.

I suppose you want to put it only in the head branch since it's not a bug
fix.


Index: objc-features.texi
===================================================================
RCS file: /cvs/gcc/gcc/libobjc/objc-features.texi,v
retrieving revision 1.7
diff -u -r1.7 objc-features.texi
--- objc-features.texi	2001/01/12 17:06:15	1.7
+++ objc-features.texi	2001/02/28 16:19:58
@@ -21,6 +21,7 @@
 * Type encoding::               
 * Garbage Collection::          
 * Constant string objects::     
+* compatibility_alias::
 @end menu
 
 @node Executing code before main, Type encoding, Top, Top
@@ -386,7 +387,7 @@
 as argument.
 
 @c =========================================================================
-@node Constant string objects,  , Garbage Collection, Top
+@node Constant string objects, compatibility_alias , Garbage Collection, Top
 @comment  node-name,  next,  previous,  up
 @section Constant string objects
 
@@ -429,6 +430,36 @@
 as argument to this option. It is possible to have multiple compilation
 units referring to different constant string classes, neither the
 compiler nor the linker impose any restrictions in doing this.
+
+@c =========================================================================
+@node compatibility_alias,  , Constant string objects, Top
+@comment  node-name,  next,  previous,  up
+@section compatibility_alias
+
+This is a feature of the Objective-C compiler rather than of the
+runtime, anyway since it is documented nowhere and its existence was
+forgotten, we are documenting it here.
+
+The keyword @code{@@compatibility_alias} allows you to define a class name 
+as equivalent to another class name.  For example: 
+
+@example
+@@compatibility_alias WOApplication GSWApplication;
+@end example
+
+tells the compiler that each time it encounters @code{WOApplication} as 
+a class name, it should replace it with @code{GSWApplication} (that is, 
+@code{WOApplication} is just an alias for @code{GSWApplication}).
+
+There are some constraints on how this can be used - 
+
+@itemize @bullet 
+
+@item @code{WOApplication} (the alias) must not be an existing class;
+
+@item @code{GSWApplication} (the real class) must be an existing class.
+
+@end itemize
 
 @bye