Realtime usage documentation

content/realtime/types.textile

@@ -9,9 +9,13 @@ jump_to:
     - Paginated Result
     - Token Request
     - Token Details
+    - Error Info
     - AblyException#ably-exception
   Other Types:
     - Client Options
+    - Completion Listener
+    - Connection State enum#connection-state
+    - Connection State Change
     - Deferrable
 ---
 
@@ -82,6 +86,27 @@ h3(#client-options).
 
 <%= partial 'types/_client_options' %>
 
+h3(#completion-listener).
+  java:   io.ably.realtime.CompletionListener
+
+blang[java].
+  <%= partial 'types/_completion_listener', indent: 2, skip_first_indent: true %>
+
+h3(#connection-state).
+  ruby:   Connection::STATE enum
+  java:   io.ably.realtime.ConnectionState enum
+
+<%= partial 'types/_connection_state' %>
+
+h3(#connection-state-change).
+  javascript,nodejs:    ConnectionStateChange Object
+  java:                 ConnectionStateChange
+
+blang[java,javascript,nodejs].
+  <%= partial 'types/_connection_state_change', indent: 2, skip_first_indent: true %>
+
+&nbsp;
+
 blang[ruby].
   h3(#deferrable).
     ruby: Ably::Util::SafeDeferrable

content/realtime/usage.textile

@@ -155,7 +155,7 @@ A reference to the "@Connection@":/realtime/connection object for this library i
 blang[ruby].
   h6(#rest-client). rest_client
 
-  A reference to the "REST Client":/rest/usage configured with the same "@ClientOptions@":#client-options.  The Realtime library is a superset of the REST library, however accessing methods in the REST library, unlike the Realtime library, are blocking operations.
+  A reference to the "REST Client":/rest/usage configured with the same "@ClientOptions@":#client-options. The Realtime library is a superset of the REST library, however accessing methods in the REST library, unlike the Realtime library, are blocking operations.
 
 h2(#methods).
   default: AblyRealtime Methods
@@ -166,19 +166,37 @@ h6(#close). close
 
 bq(definition).
   default: close()
-  ruby:    close(&block)
+  ruby:    close -> "EventMachine::Deferrable":/realtime/types#deferrable -> yields "@Connection@":/realtime/connection
   java:    public void close()
 
-This simply calls <span lang="default">"@connection.close()@":/realtime/connection#close</span><span lang="ruby">"@connection.close@":/realtime/connection#close</span> and causes the connection to close, entering the @closing@ state. Once closed, the library will not attempt to re-establish the connection without an explicit call to <span lang="default">"@connect()@":/realtime/connection#connect</span><span lang="ruby">"@connect@":/realtime/connection#connect</span>.
+This calls <span lang="default">"@connection.close()@":/realtime/connection#close</span><span lang="ruby">"@connection.close@":/realtime/connection#close</span> and causes the connection to close, entering the @closing@ state. Once @closed@, the library will not attempt to re-establish the connection without an explicit call to <span lang="default">"@connect()@":/realtime/connection#connect</span><span lang="ruby">"@connect@":/realtime/connection#connect</span>.
+
+blang[ruby].
+  h4. Returns
+
+  A "@Deferrable@":/realtime/types#deferrable object is returned from this method.
+
+  On successfully closing the connection, the registered success callbacks for the "@Deferrable@":/realtime/types#deferrable and any block provided to this method yields a "@Connection@":/realtime/connection object.
+
+  Failure to close the connection will trigger the errback callbacks of the "@Deferrable@":/realtime/types#deferrable with an "@ErrorInfo@":#error-info object containing an error response as defined in the "REST API":/rest-api#common documentation.
 
 h6(#connect). connect
 
 bq(definition).
   default: connect()
-  ruby:    connect(&block)
+  ruby:    connect -> "EventMachine::Deferrable":/realtime/types#deferrable -> yields "@Connection@":/realtime/connection
   java:    public void connect()
 
-Explicitly calling @connect@ is unnecessary unless the "@ClientOption@":#client-option <span lang="default">@connectAutomatically@</span><span lang="ruby">@connect_automatically@</span> is disabled. This method simply calls <span lang="default">"@connection.connect()@":/realtime/connection#connect</span><span lang="ruby">"@connection.connect@":/realtime/connection#connect</span> and causes the connection to open, entering the @connecting@ state.
+Explicitly calling @connect@ is unnecessary unless the "@ClientOption@":#client-option <span lang="default">@connectAutomatically@</span><span lang="ruby">@connect_automatically@</span> is disabled. This method calls <span lang="default">"@connection.connect()@":/realtime/connection#connect</span><span lang="ruby">"@connection.connect@":/realtime/connection#connect</span> and causes the connection to open, entering the @connecting@ state.
+
+blang[ruby].
+  h4. Returns
+
+  A "@Deferrable@":/realtime/types#deferrable object is returned from this method.
+
+  On successfully connecting to Ably, the registered success callbacks for the "@Deferrable@":/realtime/types#deferrable and any block provided to this method yields a "@Connection@":/realtime/connection object.
+
+  Failure to connect will trigger the errback callbacks of the "@Deferrable@":/realtime/types#deferrable with an "@ErrorInfo@":#error-info object containing an error response as defined in the "REST API":/rest-api#common documentation.
 
 h6(#stats). stats
 

content/types/_completion_listener.textile

@@ -0,0 +1,11 @@
+A <span lang="java">@io.ably.realtime.CompletionListener@</span> is an interface allowing a client to be notified of the outcome of an asynchronous operation.
+
+```[java]
+  public interface CompletionListener {
+    // Called when the associated operation completes successfully,
+    public void onSuccess();
+
+    // Called when the associated operation completes with an error.
+    public void onError(ErrorInfo reason);
+  }
+```

content/types/_connection_state.textile

@@ -0,0 +1,54 @@
+blang[java].
+  @io.ably.realtime.ConnectionState@ is an enum representing all the "@Realtime Connection@ states":/realtime/connection#connection-states.
+
+  ```[java]
+    public enum ConnectionState {
+      initialized,   // 0
+      connecting,    // 1
+      connected,     // 2
+      disconnected,  // 3
+      suspended,     // 4
+      closing,       // 5
+      closed,        // 6
+      failed         // 7
+    }
+  ```
+
+blang[ruby].
+  @Ably::Realtime::Connection::STATE@ is an enum-like value representing all the "@Realtime Connection@ states":/realtime/connection#connection-states. @STATE@s can be represented interchangeably as either symbols or constants.
+
+  h4. Symbol states
+
+  ```[ruby]
+    :initialized # =>  0
+    :connecting # =>   1
+    :connected # =>    2
+    :disconnected # => 3
+    :suspended # =>    4
+    :closing # =>      5
+    :closed # =>       6
+    :failed # =>       7
+  ```
+
+  h4. Constant states
+
+  ```[ruby]
+    Connection::STATE.Initialized # =>  0
+    Connection::STATE.Connecting # =>   1
+    Connection::STATE.Connected # =>    2
+    Connection::STATE.Disconnected # => 3
+    Connection::STATE.Suspended # =>    4
+    Connection::STATE.Closing # =>      5
+    Connection::STATE.Closed # =>       6
+    Connection::STATE.Failed # =>       7
+  ```
+
+  h4. Example usage
+
+  ```[ruby]
+    # Example with symbols
+    client.connection.on(:connected) { ... }
+
+    # Example with constants
+    client.connection.on(Ably::Realtime::Connection::STATE.Connected) { ... }
+  ```

content/types/_connection_state_change.textile

@@ -0,0 +1,11 @@
+A <span lang="java">@io.ably.realtime.ConnectionStateListener.ConnectionStateChange@</span><span lang="default">@ConnectionStateChange@</span> is a type encapsulating state change information emitted by an object that implements an @EventEmitter@
+
+h4.
+  default: Properties
+  java:    Members
+  ruby:    Attributes
+
+- @previous@ := the previous state<br>__Type: <span lang="default">String</span><span lang="java">ConnectionState</span>__
+- @current@ := the new state<br>__Type: <span lang="default">String</span><span lang="java">ConnectionState</span>__
+- @reason@ := an "@ErrorInfo@":#error-info containing any information relating to the transition<br>__Type: "@ErrorInfo@":#error-info__
+- <span lang="default">@retryIn@</span><span lang="ruby">@retry_in@</span> :=  Timestamp at which the library will retry a connection where applicable, as milliseconds since the epoch<br>__Type: <span lang="default">Integer</span><span lang="java">Long Integer</span><span lang="ruby">Time</span>__