Cleaning / code review

matrix-sdk-android/src/main/java/im/vector/matrix/android/api/session/room/model/annotation/RelationService.kt

@@ -16,11 +16,31 @@
 package im.vector.matrix.android.api.session.room.model.annotation
 
 import im.vector.matrix.android.api.session.events.model.Event
-import im.vector.matrix.android.api.session.room.model.message.MessageContent
-import im.vector.matrix.android.api.session.room.timeline.TimelineEvent
 import im.vector.matrix.android.api.util.Cancelable
 
-//TODO rename in relationService?
+/**
+ * In some cases, events may wish to reference other events.
+ * This could be to form a thread of messages for the user to follow along with,
+ * or to provide more context as to what a particular event is describing.
+ * Relation are used to associate new information with an existing event.
+ *
+ * Relations are events which have an m.relates_to mixin in their contents,
+ * and the new information they convey is expressed in their usual event type and content.
+ *
+ * Three types of relations are defined, each defining different behaviour when aggregated:
+ *
+ *  m.annotation - lets you define an event which annotates an existing event.
+ *                  When aggregated, groups events together based on key and returns a count.
+ *                  (aka SQL's COUNT) These are primarily intended for handling reactions.
+ *
+ *  m.replace - lets you define an event which replaces an existing event.
+ *             When aggregated, returns the most recent replacement event. (aka SQL's MAX)
+ *             These are primarily intended for handling edits.
+ *
+ *  m.reference - lets you define an event which references an existing event.
+ *              When aggregated, currently doesn't do anything special, but in future could bundle chains of references (i.e. threads).
+ *              These are primarily intended for handling replies (and in future threads).
+ */
 interface RelationService {
 
 
@@ -63,6 +83,12 @@ interface RelationService {
     fun editTextMessage(targetEventId: String, newBodyText: String, newBodyAutoMarkdown: Boolean, compatibilityBodyText: String = "* $newBodyText"): Cancelable
 
 
-    fun replyToMessage(eventReplied: Event, replyText: String) : Cancelable?
+    /**
+     * Reply to an event in the timeline (must be in same room)
+     * https://matrix.org/docs/spec/client_server/r0.4.0.html#id350
+     * @param eventReplied the event referenced by the reply
+     * @param replyText the reply text
+     */
+    fun replyToMessage(eventReplied: Event, replyText: String): Cancelable?
 
 }

matrix-sdk-android/src/main/java/im/vector/matrix/android/api/session/room/send/SendService.kt

@@ -31,9 +31,17 @@ interface SendService {
      * Method to send a text message asynchronously.
      * @param text the text message to send
      * @param msgType the message type: MessageType.MSGTYPE_TEXT (default) or MessageType.MSGTYPE_EMOTE
+     * @param autoMarkdown If true, the SDK will generate a formatted HTML message from the body text if markdown syntax is present
      * @return a [Cancelable]
      */
     fun sendTextMessage(text: String, msgType: String = MessageType.MSGTYPE_TEXT, autoMarkdown: Boolean = false): Cancelable
+
+    /**
+     * Method to send a text message with a formatted body.
+     * @param text the text message to send
+     * @param formattedText The formatted body using MessageType#FORMAT_MATRIX_HTML
+     * @return a [Cancelable]
+     */
     fun sendFormattedTextMessage(text: String,formattedText: String): Cancelable
 
     /**
@@ -50,6 +58,11 @@ interface SendService {
      */
     fun sendMedias(attachments: List<ContentAttachmentData>): Cancelable
 
+    /**
+     * Redacts (delete) the given event.
+     * @param event The event to redact
+     * @param reason Optional reason string
+     */
     fun redactEvent(event: Event, reason: String?): Cancelable
 
 }

matrix-sdk-android/src/main/java/im/vector/matrix/android/internal/session/room/annotation/DefaultRelationService.kt

@@ -179,11 +179,7 @@ internal class DefaultRelationService(private val roomId: String,
 
     }
 
-    /**
+
-     * Reply to an event in the timeline
-     * Users may wish to reference another message when forming their own message
-     * https://matrix.org/docs/spec/client_server/r0.4.0.html#id350
-     */
     override fun replyToMessage(eventReplied: Event, replyText: String): Cancelable? {
         val event = eventFactory.createReplyTextEvent(roomId, eventReplied, replyText)?.also {
             saveLocalEcho(it)

matrix-sdk-android/src/main/java/im/vector/matrix/android/internal/session/room/send/LocalEchoEventFactory.kt

@@ -231,7 +231,7 @@ internal class LocalEchoEventFactory(private val credentials: Credentials, priva
 //        This is where the reply goes.
         val body = bodyForReply(eventReplied.content.toModel<MessageContent>())
         val replyFallbackTemplateFormatted = """
-           <mx-reply><blockquote><a href="%s">${stringProvider.getString(R.string.in_reply_to)}</a><a href="%s">%s</a><br />%s</blockquote></mx-reply>%s
+           <mx-reply><blockquote><a href="%s">${stringProvider.getString(R.string.message_reply_to_prefix)}</a><a href="%s">%s</a><br />%s</blockquote></mx-reply>%s
         """.trimIndent().format(permalink, userLink, userId, body.second ?: body.first, replyText)
 //
 //        > <@alice:example.org> This is the original body
@@ -272,10 +272,10 @@ internal class LocalEchoEventFactory(private val credentials: Credentials, priva
                 }
                 return content.body to formattedText
             }
-            MessageType.MSGTYPE_FILE -> return stringProvider.getString(R.string.sent_a_file) to null
+            MessageType.MSGTYPE_FILE -> return stringProvider.getString(R.string.reply_to_a_file) to null
-            MessageType.MSGTYPE_AUDIO -> return stringProvider.getString(R.string.sent_an_audio_file) to null
+            MessageType.MSGTYPE_AUDIO -> return stringProvider.getString(R.string.reply_to_an_audio_file) to null
-            MessageType.MSGTYPE_IMAGE -> return stringProvider.getString(R.string.sent_an_image) to null
+            MessageType.MSGTYPE_IMAGE -> return stringProvider.getString(R.string.reply_to_an_image) to null
-            MessageType.MSGTYPE_VIDEO -> return stringProvider.getString(R.string.sent_a_video) to null
+            MessageType.MSGTYPE_VIDEO -> return stringProvider.getString(R.string.reply_to_a_video) to null
             else -> return (content?.body ?: "") to null
 
         }

matrix-sdk-android/src/main/java/im/vector/matrix/android/internal/util/StringProvider.kt

@@ -20,7 +20,7 @@ import android.content.res.Resources
 import androidx.annotation.NonNull
 import androidx.annotation.StringRes
 
-class StringProvider(private val resources: Resources) {
+internal class StringProvider(private val resources: Resources) {
 
     /**
      * Returns a localized string from the application's package's

matrix-sdk-android/src/main/res/values/strings_riotX.xml

@@ -1,9 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<resources>
-    <!-- Strings not defined in Riot -->
-    <string name="in_reply_to">In reply to</string>
-    <string name="sent_a_file">sent a file.</string>
-    <string name="sent_an_image">sent an image.</string>
-    <string name="sent_a_video">sent a video.</string>
-    <string name="sent_an_audio_file">sent an audio file.</string>
-</resources>