From df144d00c8a8b0a306c28d1a0f874b197ffaa6bf Mon Sep 17 00:00:00 2001 From: CaS Date: Fri, 4 Apr 2003 10:59:11 +0000 Subject: [PATCH] Added documentation git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@16352 72102866-910b-0410-8b05-ffd578937521 --- ChangeLog | 2 +- Headers/gnustep/base/NSInvocation.h | 17 +++- Source/NSInvocation.m | 122 +++++++++++++++++++++++++--- 3 files changed, 126 insertions(+), 15 deletions(-) diff --git a/ChangeLog b/ChangeLog index 10780f5ac..8bdafcd44 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,7 +1,7 @@ 2003-04-04 Richard Frith-Macdonald * Headers/Foundation/NSInvocation: Added NS_INVOCATION asnd NS_MESSAGE - * Source/NSInvocation.m: Support the two new macros. + * Source/NSInvocation.m: Support the two new macros. Documented. * Testing/nsinvocation.m: Trivial tests added. * Documentation/OpenStepCompliance.gsdoc: Updated. diff --git a/Headers/gnustep/base/NSInvocation.h b/Headers/gnustep/base/NSInvocation.h index 6abc40eb7..8c1bcf8f3 100644 --- a/Headers/gnustep/base/NSInvocation.h +++ b/Headers/gnustep/base/NSInvocation.h @@ -1,7 +1,7 @@ /* Interface for NSInvocation for GNUStep - Copyright (C) 1998 Free Software Foundation, Inc. + Copyright (C) 1998,2003 Free Software Foundation, Inc. - Written: Richard Frith-Macdonald + Author: Richard Frith-Macdonald Date: 1998 Based on code by: Andrew Kachites McCallum @@ -103,12 +103,25 @@ + (NSInvocation*) _returnInvocationAndDestroyProxy: (id)proxy; @end +/** + * Creates and returns an autoreleased invocation containing a + * message to an instance of the class. The 'message' consists + * of selector and arguments like a standard ObjectiveC method + * call.
+ * Before using the returned invocation, you need to set its target. + */ #define NS_INVOCATION(class, message...) ({\ id __proxy = [NSInvocation _newProxyForInvocation: class]; \ [__proxy message]; \ [NSInvocation _returnInvocationAndDestroyProxy: __proxy]; \ }) +/** + * Creates and returns an autoreleased invocation containing a + * message to the target object. The 'message' consists + * of selector and arguments like a standard ObjectiveC method + * call. + */ #define NS_MESSAGE(target, message...) ({\ id __proxy = [NSInvocation _newProxyForMessage: target]; \ [__proxy message]; \ diff --git a/Source/NSInvocation.m b/Source/NSInvocation.m index 23f4bcad8..1a9a00a6e 100644 --- a/Source/NSInvocation.m +++ b/Source/NSInvocation.m @@ -1,7 +1,7 @@ /** Implementation of NSInvocation for GNUStep - Copyright (C) 1998 Free Software Foundation, Inc. + Copyright (C) 1998,2003 Free Software Foundation, Inc. - Written: Richard Frith-Macdonald + Author: Richard Frith-Macdonald Date: August 1998 Based on code by: Andrew Kachites McCallum @@ -54,6 +54,33 @@ static Class NSInvocation_concrete_class; @interface GSMessageProxy : GSInvocationProxy @end + + +/** + *

The NSInvocation class implements a mechanism of constructing + * messages (as NSInvocation instances), sending these to other + * objects, and handling the returned values. + *

+ *

An NSInvocation object may contain a target object to which a + * message can be sent, or may send the message to an arbitrary object.
+ * Each message consists of a selector for that method and an argument + * list. Once the message has been sent, the invocation will contain + * a return value whose contents may be copied out of it. + *

+ *

The target, selector, and arguments of an instance be constructed + * dynamically, providing a great deal of power/flexibility. + *

+ *

The sending of the message to the target object (using the -invoke + * or -invokeWithTarget: method) can be done at any time, but a standard + * use of this is by the [NSObject-forwardInvocation:] method which is + * called whenever a method is not implemented by the class of the + * object to which it was sent. + *

+ *

Related to the class are two convenience macros ... NS_MESSAGE() + * and NS_INVOCATION() to allow easy construction of invocations with + * all the arguments set up. + *

+ */ @implementation NSInvocation #ifdef USE_LIBFFI @@ -244,6 +271,11 @@ _arg_addr(NSInvocation *inv, int index) } } +/** + * Copies the invocations return value to the location pointed to by buffer + * if a return value has been set (see the -setReturnValue: method).
+ * If there isn't a return value then this method raises an exception. + */ - (void) getReturnValue: (void*)buffer { const char *type; @@ -267,11 +299,23 @@ _arg_addr(NSInvocation *inv, int index) } } +/** + * Returns the selector of the invocation (the argument at index 1) + */ - (SEL) selector { return _selector; } +/** + * Sets the argument identified by index from the memory location specified + * by the buffer argument.
+ * Using an index of 0 is equivalent to calling -setTarget: and using an + * argument of 1 is equivalent to -setSelector:
+ * Proper arguments start at index 2.
+ * If -retainArguments was called, then any object argument set in the + * receiver is retained by it. + */ - (void) setArgument: (void*)buffer atIndex: (int)index { @@ -338,6 +382,9 @@ _arg_addr(NSInvocation *inv, int index) } } +/** + * Sets the return value of the invocation to the item that buffer points to. + */ - (void) setReturnValue: (void*)buffer { const char *type; @@ -361,11 +408,18 @@ _arg_addr(NSInvocation *inv, int index) _validReturn = YES; } +/** + * Sets the selector for the invocation. + */ - (void) setSelector: (SEL)aSelector { _selector = aSelector; } +/** + * Sets the target object for the invocation.
+ * If -retainArguments was called, then the target is retained. + */ - (void) setTarget: (id)anObject { if (_argsRetained) @@ -375,20 +429,27 @@ _arg_addr(NSInvocation *inv, int index) _target = anObject; } +/** + * Returns the target object of the invocation. + */ - (id) target { return _target; } -/* - * Managing arguments. +/** + * Returns a flag to indicate whether object arguments of the invocation + * (including its target) are retained by the invocation. */ - - (BOOL) argumentsRetained { return _argsRetained; } +/** + * Instructs the invocation to retain its object arguments (including the + * target). The default is not to retain them. + */ - (void) retainArguments { if (_argsRetained) @@ -438,15 +499,17 @@ _arg_addr(NSInvocation *inv, int index) } } -/* - * Dispatching an Invocation. +/** + * Sends the message encapsulated in the invocation to its target. */ - - (void) invoke { [self invokeWithTarget: _target]; } +/** + * Sends the message encapsulated in the invocation to anObject. + */ - (void) invokeWithTarget: (id)anObject { id old_target; @@ -524,10 +587,9 @@ _arg_addr(NSInvocation *inv, int index) _validReturn = YES; } -/* - * Getting the method _signature. +/** + * Returns the method signature of the invocation. */ - - (NSMethodSignature*) methodSignature { return _sig; @@ -648,8 +710,19 @@ _arg_addr(NSInvocation *inv, int index) @end +/** + * Provides some minor extensions and some utility methods to aid + * integration of NSInvocation with the ObjectiveC runtime. + */ @implementation NSInvocation (GNUstep) +/** + * Internal use.
+ * Initialises the receiver with a known selector and argument list + * as supplied to the forward:: method by the ObjectiveC runtime + * when it is unable to locate an implementation for mthe selector + * in a class. + */ - (id) initWithArgframe: (arglist_t)frame selector: (SEL)aSelector { [self subclassResponsibility: _cmd]; @@ -694,6 +767,10 @@ _arg_addr(NSInvocation *inv, int index) return [self initWithMethodSignature: newSig]; } +/** + * Initialises the reciever with the specified target, selector, and + * a variable number of arguments. + */ - (id) initWithTarget: anObject selector: (SEL)aSelector, ... { va_list ap; @@ -797,23 +874,44 @@ _arg_addr(NSInvocation *inv, int index) return self; } +/** + * Internal use.
+ * Provides a return frame that the ObjectiveC runtime can use to + * return the result of an invocation to a calling function. + */ - (void*) returnFrame: (arglist_t)argFrame { [self subclassResponsibility: _cmd]; return NULL; } +/** + * Returns the status of the flag set by -setSendsToSuper: + */ - (BOOL) sendsToSuper { return _sendToSuper; } +/** + * Sets the flag to tell the invocation that it should actually invoke a + * method in the superclass of the target rather than the method of the + * target itsself.
+ * This extension permits an invocation to act like a regular method + * call sent to super in the method of a class. + */ - (void) setSendsToSuper: (BOOL)flag { _sendToSuper = flag; } +@end -/* These next three are for internal use only ... not public API */ +/** + * These methods are for internal use only ... not public API
+ * They are used by the NS_INVOCATION() and NS_MESSAGE() macros to help + * create invocations. + */ +@implementation NSInvocation (MacroSetup) + (id) _newProxyForInvocation: (id)target { return [GSInvocationProxy _newWithTarget: target];