objc.h: Updated comments.

2010-10-11  Nicola Pero  <nicola.pero@meta-innovation.com>

        * objc/objc.h: Updated comments.
        * objc/objc-api.h: (object_copy): Added one argument; use a
        #define to maintain backwards-compatibility.  Moved
        _objc_object_alloc, _objc_object_copy, _objc_object_dispose and
        objc_get_uninstalled_dtable into
        objc/deprecated/objc_get_uninstalled_dtable.h and
        objc/deprecated/objc_object_alloc.h.  Include these files.
        * objc/deprecated/objc_get_uninstalled_dtable.h: New.
        * objc/deprecated/objc_object_alloc.h: New.
        * objc/runtime.h (set_getName): New.
        (sel_getType): New.
        (sel_getUid): New.
        (sel_registerName): New.
        (sel_registerTypedName): New.
        (sel_isEqual): New.
        (class_createInstance): New.
        (object_copy): New.
        (object_dispose): New.
        * objects.c: Do not include tconfig.h.  Include gc_typed.h if
        building the garbage collection version.
        (__objc_object_alloc): Removed.
        (__objc_object_copy): Removed.
        (__objc_object_dispose): Removed.
        (class_createInstance): New from code in class_create_instance.
        Cast second argument of GC_malloc_explicitly_typed.  Use
        objc_calloc.  Do not call _objc_object_alloc.
        (class_create_instance): Call class_createInstance.
        (object_copy): Added extraBytes argument.  Do not call
        _objc_object_copy.
        (object_dispose): Do not call _objc_object_dispose.
        * memory.c (objc_free): When using garbage collection, mark the
        argument as unused.
        * selector.c (sel_getName): New.
        (sel_get_name): Call sel_getName.
        (sel_getType): New.
        (sel_get_type): Call sel_getType.
        (sel_registerName): New.
        (sel_register_name): Call sel_registerName.
        (sel_registerTypedName): New.
        (sel_register_typed_name): Call sel_registerTypedName.
        (sel_getUid): New.
        (sel_get_uid): Call sel_getUid.

From-SVN: r165264

1 files changed, 10 insertions, 12 deletions

diff --git a/libobjc/objc/objc.h b/libobjc/objc/objc.h
index 6c3214f..76812ad 100644
--- a/libobjc/objc/objc.h
+++ b/libobjc/objc/objc.h
@@ -88,22 +88,20 @@ typedef struct objc_class *Class;
 #include "deprecated/MetaClass.h"
 #include "deprecated/struct_objc_class.h"
 
-/* An 'id' is an object of an unknown class.  The struct objc_object
-   is private and what you see here is only the beginning of the
-   struct.  In theory, the fact that 'class_pointer' is public means
-   that if you have any object 'object', you can immediately get its
-   class by using '((id)object)->class_pointer', but this is not
-   recommended; you should use object_get_class(object) instead.
+/* An 'id' is an object of an unknown class.  The way the object data
+   is stored inside the object is private and what you see here is
+   only the beginning of the actual struct.  The first field is always
+   a pointer to the Class that the object belongs to.  If performance
+   is paramount, you can use this knowledge to get the class of an
+   object by doing '((id)object)->class_pointer'.
 */
 typedef struct objc_object
 {
   /* 'class_pointer' is the Class that the object belongs to.  In case
-     of a Class object, this pointer points to the meta class.  */
-  /* Note that the Apple/NeXT runtime calls this variable 'isa'.
-     TODO: Decide if we want to call it 'isa' too.  TODO: Why not
-     simply hide this pointer and force users to use the proper API to
-     get it ?
-  */
+     of a Class object, this pointer points to the meta class.
+
+     Compatibility Note: The Apple/NeXT runtime calls this field
+     'isa'.  */
   Class class_pointer;
 } *id;