Extended/updated objc documentation on constant string classes

From-SVN: r57247

gcc/ChangeLog

+Tue Sep 17 13:40:13 2002  Nicola Pero  <n.pero@mi.flashnet.it>
+
+	* doc/objc.texi (Constant string objects): Extended documentation
+	to make clear that the constant string class ivar layout is
+	completely fixed.
+	
 2002-09-17  Roger Sayle  <roger@eyesopen.com>
 
 	* cfgrtl.c (flow_delete_block_noexpunge): Delete orphaned

gcc/doc/objc.texi

@@ -396,7 +396,7 @@ prefixing a C constant string with the character @samp{@@}:
   id myString = @@"this is a constant string object";
 @end example
 
-The constant string objects are usually instances of the
+The constant string objects are by default instances of the
 @code{NXConstantString} class which is provided by the GNU Objective-C
 runtime.  To get the definition of this class you must include the
 @file{objc/NXConstStr.h} header file.
@@ -409,8 +409,9 @@ as @code{NXConstantString}'s structure:
 
 @example
 
-@@interface NXConstantString : Object
+@@interface MyConstantStringClass
 @{
+  Class isa;
   char *c_string;
   unsigned int len;
 @}
@@ -418,15 +419,31 @@ as @code{NXConstantString}'s structure:
 
 @end example
 
-User class libraries may choose to inherit the customized constant
-string class from a different class than @code{Object}.  There is no
-requirement in the methods the constant string class has to implement.
-
-When a file is compiled with the @option{-fconstant-string-class} option,
-all the constant string objects will be instances of the class specified
-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.
+@code{NXConstantString} inherits from @code{Object}; user class
+libraries may choose to inherit the customized constant string class
+from a different class than @code{Object}.  There is no requirement in
+the methods the constant string class has to implement, but the final
+ivar layour of the class must be the compatible with the given
+structure.
+
+When the compiler creates the statically allocated constant string
+object, the @code{c_string} field will be filled by the compiler with
+the string; the @code{length} field will be filled by the compiler with
+the string length; the @code{isa} pointer will be filled with
+@code{NULL} by the compiler, and it will later be fixed up automatically
+at runtime by the GNU Objective-C runtime library to point to the class
+which was set by the @option{-fconstant-string-class} option when the
+object file is loaded (if you wonder how it works behind the scenes, the
+name of the class to use, and the list of static objects to fixup, are
+stored by the compiler in the object file in a place where the GNU
+runtime library will find them at runtime).
+
+As a result, when a file is compiled with the
+@option{-fconstant-string-class} option, all the constant string objects
+will be instances of the class specified 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