Minor documentation improvements

robbiehanson · robbiehanson · commit 3f87a40db6b3 · 2014-07-30T16:18:22.000-07:00
diff --git a/Core/XMPPInternal.h b/Core/XMPPInternal.h
@@ -38,18 +38,40 @@ extern NSString *const XMPPStreamDidChangeMyJIDNotification;
 @interface XMPPStream (/* Internal */)
 
 /**
- * Categories on XMPPStream should maintain thread safety by dispatching through the internal xmppQueue.
- * They may also need to ensure the stream is in the proper state for their activity.
+ * XMPPStream maintains thread safety by dispatching  through the internal serial xmppQueue.
+ * Subclasses of XMPPStream MUST follow the same technique:
+ * 
+ * dispatch_block_t block = ^{
+ *     // Code goes here
+ * };
+ * 
+ * if (dispatch_get_specific(xmppQueueTag))
+ *   block();
+ * else
+ *   dispatch_sync(xmppQueue, block);
+ *
+ * Category methods may or may not need to dispatch through the xmppQueue.
+ * It depends entirely on what properties of xmppStream the category method needs to access.
+ * For example, if a category only accesses a single property, such as the rootElement,
+ * then it can simply fetch the atomic property, inspect it, and complete its job.
+ * However, if the category needs to fetch multiple properties, then it likely needs to fetch all such
+ * properties in an atomic fashion. In this case, the category should likely go through the xmppQueue,
+ * to ensure that it gets an atomic state of the xmppStream in order to complete its job.
 **/
+@property (nonatomic, readonly) dispatch_queue_t xmppQueue;
+@property (nonatomic, readonly) void *xmppQueueTag;
 
-@property (readonly) dispatch_queue_t xmppQueue;
-@property (readonly) void *xmppQueueTag;
-@property (readonly) XMPPStreamState state;
+/**
+ * Returns the current state of the xmppStream.
+**/
+@property (atomic, readonly) XMPPStreamState state;
 
 /**
  * This method is for use by xmpp authentication mechanism classes.
- * They should send elements using this method instead of the public sendElement classes,
+ * They should send elements using this method instead of the public sendElement methods,
  * as those methods don't send the elements while authentication is in progress.
+ * 
+ * @see XMPPSASLAuthentication
 **/
 - (void)sendAuthElement:(NSXMLElement *)element;
 
diff --git a/Core/XMPPStream.m b/Core/XMPPStream.m
@@ -2703,8 +2703,10 @@ - (void)resendMyPresence
 
 /**
  * This method is for use by xmpp authentication mechanism classes.
- * They should send elements using this method instead of the public sendElement classes,
+ * They should send elements using this method instead of the public sendElement methods,
  * as those methods don't send the elements while authentication is in progress.
+ *
+ * @see XMPPSASLAuthentication
 **/
 - (void)sendAuthElement:(NSXMLElement *)element
 {
