Comment fields in ConversationEntity related to expanding and collapsing content

app/src/main/java/com/keylesspalace/tusky/components/conversation/ConversationEntity.kt

@@ -29,6 +29,7 @@ import com.keylesspalace.tusky.entity.TimelineAccount
 import com.keylesspalace.tusky.viewdata.StatusViewData
 import java.util.Date
 
+/** A reply-tree of statuses which have been saved to disk. */
 @Entity(primaryKeys = ["id", "accountId"])
 @TypeConverters(Converters::class)
 data class ConversationEntity(
@@ -50,6 +51,7 @@ data class ConversationEntity(
     }
 }
 
+/** The account information associated with a status saved to disk. */
 data class ConversationAccountEntity(
     val id: String,
     val localUsername: String,
@@ -72,6 +74,7 @@ data class ConversationAccountEntity(
     }
 }
 
+/** A previously-displayed status which has been saved to disk. */
 @TypeConverters(Converters::class)
 data class ConversationStatusEntity(
     val id: String,
@@ -87,14 +90,20 @@ data class ConversationStatusEntity(
     val repliesCount: Int,
     val favourited: Boolean,
     val bookmarked: Boolean,
+    /** If true, post attachments are marked as sensitive content. */
     val sensitive: Boolean,
+    /** If nonempty, post text has a spoiler/content warning. */
     val spoilerText: String,
     val attachments: List<Attachment>,
     val mentions: List<Status.Mention>,
     val tags: List<HashTag>?,
+    /** If sensitive is true, then this is true when the user has chosen to expose the attachments. */
     val showingHiddenContent: Boolean,
+    /** If spoilerText is nonempty, then this is true when the user has chosen to show the text. */
     val expanded: Boolean,
+    /** If content is long (see shouldTrimStatus()), then this is *false* when the user has chosen to show all content. */
     val collapsed: Boolean,
+    /** If true, the user has chosen not to see further notifications for this status. */
     val muted: Boolean,
     val poll: Poll?,
     val language: String?

app/src/main/java/com/keylesspalace/tusky/entity/Status.kt

@@ -21,6 +21,7 @@ import com.google.gson.annotations.SerializedName
 import com.keylesspalace.tusky.util.parseAsMastodonHtml
 import java.util.Date
 
+/** A Mastodon status as the server sees it. (Distinct from ConversationStatusEntity or StatusViewData.Concrete). */
 data class Status(
     val id: String,
     val url: String?, // not present if it's reblog
@@ -38,24 +39,29 @@ data class Status(
     val reblogged: Boolean,
     val favourited: Boolean,
     val bookmarked: Boolean,
+    /** If true, post attachments are marked as sensitive content. */
     val sensitive: Boolean,
+    /** If nonempty, post text has a spoiler/content warning. */
     @SerializedName("spoiler_text") val spoilerText: String,
     val visibility: Visibility,
     @SerializedName("media_attachments") val attachments: List<Attachment>,
     val mentions: List<Mention>,
     val tags: List<HashTag>?,
     val application: Application?,
     val pinned: Boolean?,
+    /** If true, the user has chosen not to see further notifications for this status. */
     val muted: Boolean?,
     val poll: Poll?,
     val card: Card?,
     val language: String?,
+    /** If true, the server reports a user-custom content filter applies to the status. */
     val filtered: List<FilterResult>?
 ) {
 
     val actionableId: String
         get() = reblog?.id ?: id
 
+    /** If status is a reblog, the "true" status, otherwise self. */
     val actionableStatus: Status
         get() = reblog ?: this
 

app/src/main/java/com/keylesspalace/tusky/viewdata/StatusViewData.kt

@@ -25,41 +25,63 @@ import com.keylesspalace.tusky.util.shouldTrimStatus
 /**
  * Created by charlag on 11/07/2017.
  *
- * Class to represent data required to display either a notification or a placeholder.
+ * Class to represent data required to display either a status or a placeholder ("Load More" bar).
  * It is either a [StatusViewData.Concrete] or a [StatusViewData.Placeholder].
+ * Can be created either from a ConversationStatusEntity, or by helpers in ViewDataUtils.
  */
 sealed class StatusViewData {
     abstract val id: String
     var filterAction: Filter.Action = Filter.Action.NONE
 
     data class Concrete(
+        /** The Mastodon-API level information about the status. */
         val status: Status,
+        /**
+         * If StatusViewData spoilerText is nonempty, specifies whether the text content of this post
+         * is currently hidden.
+         *
+         * @return If true, post is shown. If false, it is hidden.
+         */
         val isExpanded: Boolean,
+        /**
+         * Specifies whether attachments are currently hidden as sensitive.
+         *
+         * @return If true, attachments are shown. If false, they is hidden.
+         */
         val isShowingContent: Boolean,
         /**
-         * Specifies whether the content of this post is currently limited in visibility to the first
-         * 500 characters or not.
+         * If StatusViewData isCollapsible, specifies whether the content of this post is currently
+         * limited in visibility to the first characters or not.
          *
-         * @return Whether the post is collapsed or fully expanded.
+         * @return If true, post is collapsed. If false, it is fully expanded.
          */
         val isCollapsed: Boolean,
+        /**
+         * If true, the status is "big" (has been selected by the user for detailed display).
+         */
         val isDetailed: Boolean = false
     ) : StatusViewData() {
         override val id: String
             get() = status.id
 
         /**
          * Specifies whether the content of this post is long enough to be automatically
-         * collapsed or if it should show all content regardless.
+         * collapsed or if it should show all content regardless. (See shouldTrimStatus())
          *
          * @return Whether the post is collapsible or never collapsed.
          */
         val isCollapsible: Boolean
-
         val content: Spanned
+
+        /**
+         * @return If nonempty, the spoiler/content warning text. If empty, there is no warning.
+         */
         val spoilerText: String
         val username: String
 
+        /**
+         * @return The "true" status (same as status unless this is a reblog)
+         */
         val actionable: Status
             get() = status.actionableStatus