chore: interface update

- make ErrorReason on the channel nullable
- improve docstrings

pubsub-adapter/src/main/kotlin/com/ably/pubsub/Channel.kt

@@ -4,18 +4,40 @@ import com.ably.query.OrderBy
 import io.ably.lib.types.*
 
 /**
- * An interface representing a Channel in the Ably API.
+ * An interface representing a Channel in the Ably API. This serves as the base interface
+ * for both [RealtimeChannel] and [RestChannel], providing common channel functionality
+ * such as history retrieval and presence management.
+ *
+ * A channel is the medium through which messages are distributed. Channels can represent
+ * different topics, rooms, or contexts in your application.
+ *
+ * @see <a href="https://ably.com/docs/realtime/channels">Ably Channels Documentation</a>
  */
 interface Channel {
 
   /**
    * The channel name.
+   *
+   * Channel names:
+   * - Can contain any Unicode characters except colon (':')
+   * - Are limited to 250 characters
+   * - Are case-sensitive
+   *
+   * @see <a href="https://ably.com/docs/realtime/channels#channel-naming">Channel Naming Rules</a>
    */
   val name: String
 
   /**
    * A [Presence] object.
    *
+   * The Presence object enables clients to be notified when other clients enter or leave
+   * the channel (presence events) and get the set of current members on the channel
+   * (presence state).
+   *
+   * Common use cases include:
+   * - Online status indicators
+   * - Typing indicators
+   * - User activity tracking
    *
    * Spec: RTL9
    */

pubsub-adapter/src/main/kotlin/com/ably/pubsub/RealtimeChannel.kt

@@ -31,7 +31,7 @@ interface RealtimeChannel : Channel {
    *
    * Spec: RTL4e
    */
-  val reason: ErrorInfo
+  val reason: ErrorInfo?
 
   /**
    * A [ChannelProperties] object.