Add comments from apple source code

src/libobjc/message.nim

@@ -2,36 +2,128 @@ import objc
 import runtime
 
 type
+  ComplexLD* {.importc: "_Complex long double", nodecl.} = clongdouble
   ObjcSuper* {.bycopy.} = object
-    receiver*: Id
-    superClass*: Class
-
+    ## Specifies the superclass of an instance.
+    receiver*: Id ## Specifies an instance of a class.
+    superClass*: Class ## Specifies the particular superclass of the instance to message.
 
 
 proc objcMsgSend*(self: Id; op: Sel): Id {.varargs, cdecl, importc: "objc_msgSend",
                                      dynlib: libobjc.}
+  ## Sends a message with a simple return value to an instance of a class.
+  ##
+  ## @param self A pointer to the instance of the class that is to receive the message.
+  ## @param op The selector of the method that handles the message.
+  ## @param ...
+  ##   A variable argument list containing the arguments to the method.
+  ##
+  ## @return The return value of the method.
+  ##
+  ## @note When it encounters a method call, the compiler generates a call to one of the
+  ##  functions \c objc_msgSend, \c objc_msgSend_stret, \c objc_msgSendSuper, or \c objc_msgSendSuper_stret.
+  ##  Messages sent to an object’s superclass (using the \c super keyword) are sent using \c objc_msgSendSuper;
+  ##  other messages are sent using \c objc_msgSend. Methods that have data structures as return values
+  ##  are sent using \c objc_msgSendSuper_stret and \c objc_msgSend_stret.
+
 
 proc objcMsgSendSuper*(super: ptr ObjcSuper; op: Sel): Id {.varargs, cdecl,
     importc: "objc_msgSendSuper", dynlib: libobjc.}
+  ## Sends a message with a simple return value to the superclass of an instance of a class.
+  ##
+  ## @param super A pointer to an \c objc_super data structure. Pass values identifying the
+  ##  context the message was sent to, including the instance of the class that is to receive the
+  ##  message and the superclass at which to start searching for the method implementation.
+  ## @param op A pointer of type SEL. Pass the selector of the method that will handle the message.
+  ## @param ...
+  ##   A variable argument list containing the arguments to the method.
+  ##
+  ## @return The return value of the method identified by \e op.
+  ##
+  ## @see objc_msgSend
 
 proc objcMsgSendStret*(self: Id; op: Sel) {.varargs, cdecl,
                                        importc: "objc_msgSend_stret",
                                        dynlib: libobjc.}
+  ## Sends a message with a data-structure return value to an instance of a class.
+  ##
+  ## @see objc_msgSend
 
 proc objcMsgSendSuperStret*(super: ptr ObjcSuper; op: Sel) {.varargs, cdecl,
     importc: "objc_msgSendSuper_stret", dynlib: libobjc.}
+  ## Sends a message with a data-structure return value to the superclass of an instance of a class.
+  ##
+  ## @see objc_msgSendSuper
 
-proc objcMsgSendFpret*(self: Id; op: Sel): clongdouble {.varargs, cdecl,
-    importc: "objc_msgSend_fpret", dynlib: libobjc.}
-proc objcMsgSendFp2ret*(self: Id; op: Sel) {.varargs, cdecl,
-                                        importc: "objc_msgSend_fp2ret",
-                                        dynlib: libobjc.}
+
+## Floating-point-returning Messaging Primitives
+##
+## Use these functions to call methods that return floating-point values
+## on the stack.
+## Consult your local function call ABI documentation for details.
+##
+## arm:    objc_msgSend_fpret not used
+## i386:   objc_msgSend_fpret used for `float`, `double`, `long double`.
+## x86-64: objc_msgSend_fpret used for `long double`.
+##
+## arm:    objc_msgSend_fp2ret not used
+## i386:   objc_msgSend_fp2ret not used
+## x86-64: objc_msgSend_fp2ret used for `_Complex long double`.
+##
+## These functions must be cast to an appropriate function pointer type
+## before being called.
+##
+
+when defined(amd64):
+  proc objcMsgSendFpret*(self: Id; op: Sel): clongdouble {.varargs, cdecl,
+      importc: "objc_msgSend_fpret", dynlib: libobjc.}
+    ## Sends a message with a floating-point return value to an instance of a class.
+    ##
+    ## @see objc_msgSend
+
+  proc objcMsgSendFp2ret*(self: Id; op: Sel): ComplexLD {.varargs, cdecl,
+                                          importc: "objc_msgSend_fp2ret",
+                                          dynlib: libobjc.}
+elif defined(i386):
+  proc objcMsgSendFpret*(self: Id; op: Sel): cdouble {.varargs, cdecl,
+      importc: "objc_msgSend_fpret", dynlib: libobjc.}
+    ## Sends a message with a floating-point return value to an instance of a class.
+    ##
+    ## @see objc_msgSend
+    ## @note On the i386 platform, the ABI for functions returning a floating-point value is
+    ##  incompatible with that for functions returning an integral type. On the i386 platform, therefore,
+    ##  you must use \c objc_msgSend_fpret for functions returning non-integral type. For \c float or
+    ##  \c long \c double return types, cast the function to an appropriate function pointer type first.
+
+## Direct Method Invocation Primitives
+## Use these functions to call the implementation of a given Method.
+## This is faster than calling method_getImplementation() and method_getName().
+##
+## The receiver must not be nil.
+##
+## These functions must be cast to an appropriate function pointer type
+## before being called.
 
 proc methodInvoke*(receiver: Id; m: Method): Id {.varargs, cdecl,
     importc: "method_invoke", dynlib: libobjc.}
 proc methodInvokeStret*(receiver: Id; m: Method) {.varargs, cdecl,
     importc: "method_invoke_stret", dynlib: libobjc.}
 
+## Message Forwarding Primitives
+## Use these functions to forward a message as if the receiver did not
+## respond to it.
+##
+## The receiver must not be nil.
+##
+## class_getMethodImplementation() may return (IMP)_objc_msgForward.
+## class_getMethodImplementation_stret() may return (IMP)_objc_msgForward_stret
+##
+## These functions must be cast to an appropriate function pointer type
+## before being called.
+##
+## Before Mac OS X 10.6, _objc_msgForward must not be called directly
+## but may be compared to other IMP values.
+
 proc objcMsgForward*(receiver: Id; sel: Sel): Id {.varargs, cdecl,
     importc: "_objc_msgForward", dynlib: libobjc.}
 proc objcMsgForwardStret*(receiver: Id; sel: Sel) {.varargs, cdecl,

src/libobjc/objc.nim

@@ -18,30 +18,86 @@ const
   autoreleasing* = true
 
 proc selGetName*(sel: Sel): cstring {.cdecl, importc: "sel_getName", dynlib: libobjc.}
+  ## Returns the name of the method specified by a given selector.
+  ##
+  ## @param sel A pointer of type \c SEL. Pass the selector whose name you wish to determine.
+  ##
+  ## @return A C string indicating the name of the selector.
 
 proc selRegisterName*(str: cstring): Sel {.cdecl, importc: "sel_registerName",
                                        dynlib: libobjc.}
+  ## Registers a method with the Objective-C runtime system, maps the method
+  ## name to a selector, and returns the selector value.
+  ##
+  ## @param str A pointer to a C string. Pass the name of the method you wish to register.
+  ##
+  ## @return A pointer of type SEL specifying the selector for the named method.
+  ##
+  ## @note You must register a method name with the Objective-C runtime system to obtain the
+  ##  method’s selector before you can add the method to a class definition. If the method name
+  ##  has already been registered, this function simply returns the selector.
 
 proc objectGetClassName*(obj: Id): cstring {.cdecl, importc: "object_getClassName",
     dynlib: libobjc.}
+  ## Returns the class name of a given object.
+  ##
+  ## @param obj An Objective-C object.
+  ##
+  ## @return The name of the class of which \e obj is an instance.
 
 proc objectGetIndexedIvars*(obj: Id): pointer {.cdecl,
     importc: "object_getIndexedIvars", dynlib: libobjc.}
+  ## Returns a pointer to any extra bytes allocated with an instance given object.
+  ##
+  ## @param obj An Objective-C object.
+  ##
+  ## @return A pointer to any extra bytes allocated with \e obj. If \e obj was
+  ##   not allocated with any extra bytes, then dereferencing the returned pointer is undefined.
+  ##
+  ## @note This function returns a pointer to any extra bytes allocated with the instance
+  ##  (as specified by \c class_createInstance with extraBytes>0). This memory follows the
+  ##  object's ordinary ivars, but may not be adjacent to the last ivar.
+  ## @note The returned pointer is guaranteed to be pointer-size aligned, even if the area following
+  ##  the object's last ivar is less aligned than that. Alignment greater than pointer-size is never
+  ##  guaranteed, even if the area following the object's last ivar is more aligned than that.
+  ## @note In a garbage-collected environment, the memory is scanned conservatively.
 
 proc selIsMapped*(sel: Sel): Bool {.cdecl, importc: "sel_isMapped", dynlib: libobjc.}
+  ## Identifies a selector as being valid or invalid.
+  ##
+  ## @param sel The selector you want to identify.
+  ##
+  ## @return YES if selector is valid and has a function implementation, NO otherwise.
+  ##
+  ## @warning On some platforms, an invalid reference (to invalid memory addresses) can cause
+  ##  a crash.
 
 proc selGetUid*(str: cstring): Sel {.cdecl, importc: "sel_getUid", dynlib: libobjc.}
+  ## Registers a method name with the Objective-C runtime system.
+  ##
+  ## @param str A pointer to a C string. Pass the name of the method you wish to register.
+  ##
+  ## @return A pointer of type SEL specifying the selector for the named method.
+  ##
+  ## @note The implementation of this method is identical to the implementation of \c sel_registerName.
+  ## @note Prior to OS X version 10.0, this method tried to find the selector mapped to the given name
+  ##  and returned \c NULL if the selector was not found. This was changed for safety, because it was
+  ##  observed that many of the callers of this function did not check the return value for \c NULL.
 
+
+## OBSOLETE ###############################
 type
   ObjcObjectPtrT* = distinct pointer
 
-
 proc objcRetainedObject*(obj: ObjcObjectPtrT): Id {.cdecl,
     importc: "objc_retainedObject", dynlib: libobjc.}
 proc objcUnRetainedObject*(obj: ObjcObjectPtrT): Id {.cdecl,
     importc: "objc_unretainedObject", dynlib: libobjc.}
 proc objcUnRetainedPointer*(obj: Id): ObjcObjectPtrT {.cdecl,
     importc: "objc_unretainedPointer", dynlib: libobjc.}
+###########################################
+
+## The following declarations are provided here for source compatibility.
 
 type
   ArithT* = clong