[ECO-4899] chore: rename Direction into more meaningful MessageOrder

Also added TODO for `Messages#send` function, right now in the Chat JS documentation mentioned that it's behavior is non-deterministic, which is not very good for DX

Author: ttypic

chat-android/src/main/java/com/ably/chat/Messages.kt

@@ -44,15 +44,17 @@ interface Messages : EmitsDiscontinuities {
      *
      * This method uses the Ably Chat API endpoint for sending messages.
      *
-     * Note that the Promise may resolve before OR after the message is received
+     * Note: that the suspending function may resolve before OR after the message is received
      * from the realtime channel. This means you may see the message that was just
-     * sent in a callback to `subscribe` before the returned promise resolves.
+     * sent in a callback to `subscribe` before the function resolves.
+     *
+     * TODO: Revisit this resolution policy during implementation (it will be much better for DX if this behavior is deterministic).
      *
      * @param params an object containing {text, headers, metadata} for the message
      * to be sent. Text is required, metadata and headers are optional.
-     * @returns A promise that resolves when the message was published.
+     * @returns The message was published.
      */
-    fun send(params: SendMessageParams): Message
+    suspend fun send(params: SendMessageParams): Message
 
     /**
      * An interface for listening to new messaging event
@@ -92,23 +94,23 @@ data class QueryOptions(
     val limit: Int = 100,
 
     /**
-     * The direction to query messages in.
+     * The order of messages in the query result.
      */
-    val direction: Direction = Direction.FORWARDS,
+    val orderBy: MessageOrder = MessageOrder.NewestFirst,
 ) {
     /**
      * Represents direction to query messages in.
      */
-    enum class Direction {
+    enum class MessageOrder {
         /**
          * The response will include messages from the start of the time window to the end.
          */
-        FORWARDS,
+        NewestFirst,
 
         /**
          * the response will include messages from the end of the time window to the start.
          */
-        BACKWARDS,
+        OldestFirst,
     }
 }
 

chat-android/src/main/java/com/ably/chat/Occupancy.kt

@@ -20,7 +20,6 @@ interface Occupancy : EmitsDiscontinuities {
      * Subscribe a given listener to occupancy updates of the chat room.
      *
      * @param listener A listener to be called when the occupancy of the room changes.
-     * @returns A promise resolves to the channel attachment state change event from the implicit channel attach operation.
      */
     fun subscribe(listener: Listener)
 
@@ -34,7 +33,7 @@ interface Occupancy : EmitsDiscontinuities {
     /**
      * Get the current occupancy of the chat room.
      *
-     * @returns A promise that resolves to the current occupancy of the chat room.
+     * @returns the current occupancy of the chat room.
      */
     suspend fun get(): OccupancyEvent