Add xcode documentation

Source/OCMock/NSNotificationCenter+OCMAdditions.h

@@ -10,6 +10,13 @@
 
 @interface NSNotificationCenter(OCMAdditions)
 
+/**
+ adds a mock observer for the given notification
+ @discussion This method is a convenience for setting up a mock observer by telling the notification center to call a certain selector on the mock.
+ @param notificationObserver the mock observer to register
+ @param notificationName the notification to observe
+ @param notificationSender the sender to observe
+ */
 - (void)addMockObserver:(OCMockObserver *)notificationObserver name:(NSString *)notificationName object:(id)notificationSender;
 
 @end

Source/OCMock/OCMockObject.h

@@ -15,25 +15,102 @@
 	NSMutableArray	*exceptions;
 }
 
+/**
+ Creates a mock object that can be used as if it were an instance of the supplied class
+ @param aClass class to mock
+ @return mock
+ */
 + (id)mockForClass:(Class)aClass;
+/**
+ Creates a mock object that can be used as if it were an instance of an object that implements the supplied protocol
+ @param aProtocol protocol to mock
+ @return mock
+ */
 + (id)mockForProtocol:(Protocol *)aProtocol;
+/**
+ Creates a mock object that can be used in the same way as anObject. When a method that is not stubbed is invoked it will be forwarded to anObject. When a stubbed method is invoked using a reference to anObject, rather than the mock, it will still be handled by the mock.
+ @param anObject the object to partially mock
+ @return mock
+ */
 + (id)partialMockForObject:(NSObject *)anObject;
 
+/**
+ Creates a "nice" mock for the supplied class
+ @discussion When a method is called on a mock object that has not been set up with either expect or stub the mock object will raise an exception. This fail-fast mode can be turned off by creating a "nice" mock. While nice mocks will simply ignore all unexpected methods it is possible to disallow specific methods:
+ @code
+ [[mock reject] someMethod]
+ @endcode
+ @note In fail-fast mode, if the exception is ignored, it will be rethrown when verify is called. This makes it possible to ensure that unwanted invocations from notifications etc. can be detected.
+ @param aClass class to create a "nice" mock of
+ @return mock
+ */
 + (id)niceMockForClass:(Class)aClass;
-+ (id)niceMockForProtocol:(Protocol *)aProtocol;
 
+/**
+ Creates a "nice" mock that conforms to the supplied protocol
+ @param aProtocol The protocol to mock
+ @return mock
+ */
++ (id)niceMockForProtocol:(Protocol *)aProtocol;
+/**
+ Creates a mock object that can be used to observe notifications. The mock must be registered in order to receive notifications:
+ @code
+ [notificatonCenter addMockObserver:aMock name:SomeNotification object:nil]
+ @endcode
+ Expectations can then be set up as follows:
+ @code
+ [[mock expect] notificationWithName:SomeNotification object:[OCMArg any]]
+ @endcode
+ @note Currently there is no "nice" mode for observer mocks, they will always raise an exception when an unexpected notification is received.
+ @see NSNotificationCenter+OCMAdditions.h
+ @return mock
+ */
 + (id)observerMock;
-
+/**
+ makes a mock object
+ @return mock
+ */
 - (id)init;
-
+/**
+ Sets whether the order that you tell the mock the calls you expect matters.
+ @param flag @c YES or @c NO to turn this feature on and off
+ */
 - (void)setExpectationOrderMatters:(BOOL)flag;
 
+/**
+ Tells the mock object to add a sub implementation with a chained result to a chained selector
+ @code
+ [[[mock stub] andReturn:aValue] someMethod:someArgument]
+ @endcode
+ @see http://ocmock.org/features/
+ @return returns self for method chaining
+ */
 - (id)stub;
+/**
+ Used for telling the mock that you expect the chained selector to be called.
+ @code
+ [[mock expect] someMethod:someArgument]
+ @endcode
+ Tells the mock object that @c someMethod: should be called with an argument that is equal to @c someArgument. After this setup the functionality under test should be invoked followed by @c -verify
+ @see @c -verify
+ @return self
+ */
 - (id)expect;
+/**
+ When using nice mocks it is possible to disallow specific methods:
+ @return mock
+ */
 - (id)reject;
-
+/**
+ Used to verify the mock has recieved all the messages you told it to expect
+ @discussion The verify method will raise an exception if the expected method has not been invoked.
+ */
 - (void)verify;
-
+/**
+ The partial / class mock can be returned to its original state, i.e. all stubs will be removed
+ @discussion This is only necessary if the original state must be restored before the end of the test. The mock automatically calls @c stopMocking during its own deallocation.
+ @warning If the mock object that added a stubbed class method is not deallocated the stubbed method will persist across tests. If multiple mock objects manipulate the same class at the same time the behaviour is undefined.
+ */
 - (void)stopMocking;
 
 // internal use only

Source/OCMock/OCMockRecorder.h

@@ -19,18 +19,97 @@
 - (BOOL)matchesSelector:(SEL)sel;
 - (BOOL)matchesInvocation:(NSInvocation *)anInvocation;
 - (void)releaseInvocation;
-
+/**
+ Tells the mock to return an object for the stubbed selector.
+ @code
+ [[[mock stub] andReturn:aValue] someMethod:someArgument]
+ @endcode
+ @note If the method returns a primitive type then @c andReturnValue: must be used with a value argument. It is not possible to pass primitive types directly.
+ @param anObject object to return for this stubbed selector
+ @return self (for chaining)
+ */
 - (id)andReturn:(id)anObject;
+/**
+ Tells the mock to return a value for the stubbed selector
+ @discussion If the method returns a primitive type then andReturnValue: must be used with a value argument. It is not possible to pass primitive types directly.
+ @code
+ [[[mock stub] andReturnValue:@YES] aMethodReturnABoolean:someArgument]
+ @endcode
+ @param aValue the value to return for this stubbed selector
+ @return self (for chaining)
+ */
 - (id)andReturnValue:(NSValue *)aValue;
+/**
+ The mock object will throw an exception when a message is sent to the stubbed selector
+ @code
+ [[[mock stub] andThrow:anException] someMethod:someArgument]
+ @endcode
+ @param anException the exception object to throw
+ @return self (for chaining)
+ */
 - (id)andThrow:(NSException *)anException;
+/**
+ The mock object will post a notification when a message is sent to the stubbed selector
+ @code
+ [[[mock stub] andPost:anException] someMethod:someArgument]
+ @endcode
+ @param aNotification the notification object to post
+ @return self (for chaining)
+ */
 - (id)andPost:(NSNotification *)aNotification;
+/**
+ The mock delegates the handling of an invocation to a completely different method
+ @code
+ [[[mock stub] andCall:@selector(aMethod:) onObject:anObject] someMethod:someArgument]
+ @endcode
+ @note The signature of the replacement method must be the same as that of the method that is replaced. Arguments will be passed and the return value of the replacement method is returned from the stubbed method.
+ @param selector The selector to message on the supplied object
+ @param anObject the object to message with the supplied selector
+ @return self (for chaining)
+ */
 - (id)andCall:(SEL)selector onObject:(id)anObject;
 #if NS_BLOCKS_AVAILABLE
+/**
+ If Objective-C blocks are available a block can be used to handle the invocation and set up a return value
+ @code
+ void (^theBlock)(NSInvocation *) = ^(NSInvocation *invocation) {
+ // code that reads and modifies the invocation object
+};
+[[[mock stub] andDo:theBlock] someMethod:[OCMArg any]];
+ @endcode
+ @param block a block containing the code you want executed
+ @return self (for chaining)
+ */
 - (id)andDo:(void (^)(NSInvocation *))block; 
 #endif
-- (id)andForwardToRealObject;
 
+/**
+ If using a partial mock it is possible to forward the method to the implementation in the real object
+ @code
+ [[[mock expect] andForwardToRealObject] someMethod]
+ @endcode
+ @note can be useful to simply check that a method was called
+ @return self (for chaining)
+ */
+- (id)andForwardToRealObject;
+/**
+ explicitly stub a class method
+ @discussion In cases where a class method should be stubbed but the class also has an instance method with the same name as the class method, the intent to mock the class method must be made explicit.
+ @code
+ [[[[mock stub] classMethod] andReturn:aValue] aMethod]
+ @endcode
+ @return self (for chaining)
+ */
 - (id)classMethod;
+/**
+ tells the mock to ignore non object arguments
+ @discussion Arguments that are neither objects nor pointers or selectors cannot be ignored using an any placeholder. It is possible, though, to tell the mock to ignore all non-object arguments in an invocation
+ @code
+ [[[mock expect] ignoringNonObjectArgs] someMethodWithIntArgument:0]
+ @endcode
+ @note If the method has object arguments as well as non-object arguments, the object arguments can still be constrained as usual using the methods on OCMArg.
+ @see http://www.mulle-kybernetik.com/forum/viewtopic.php?f=4&t=72
+ */
 - (id)ignoringNonObjectArgs;
 
 - (NSArray *)invocationHandlers;