Document all the post widgets

app/src/main/java/xyz/wingio/dimett/ui/widgets/posts/Card.kt

@@ -43,6 +43,9 @@ fun Card(
     }
 }
 
+/**
+ * Standard link card, displays the thumbnail image, the title, and a description
+ */
 @OptIn(ExperimentalMaterial3Api::class)
 @Composable
 fun LinkCard(
@@ -51,8 +54,9 @@ fun LinkCard(
     val ctx = LocalContext.current
     val uriHandler = LocalUriHandler.current
     var size by remember {
-        mutableStateOf(Size.ORIGINAL)
+        mutableStateOf(Size.ORIGINAL) // Position is chosen based on thumbnail size
     }
+
     val imageRequest = remember {
         ImageRequest.Builder(ctx)
             .error(R.drawable.img_preview_placeholder)
@@ -65,7 +69,7 @@ fun LinkCard(
             }
             .build()
     }
-    val isBig = size.width.pxOrElse { 0 } > size.height.pxOrElse { 0 }
+    val isBig = size.width.pxOrElse { 0 } > size.height.pxOrElse { 0 } // Checks if the width is larger than the height (Is in landscape)
     val aspectRatio = size.width.pxOrElse { 0 }.toFloat() / size.height.pxOrElse { 0 }.toFloat()
 
     ElevatedCard(
@@ -75,7 +79,7 @@ fun LinkCard(
         modifier = Modifier
             .fillMaxWidth()
     ) {
-        if (isBig) {
+        if (isBig) { // Landscape images get placed above the title and description
             AsyncImage(
                 model = imageRequest,
                 contentDescription = null,
@@ -91,7 +95,7 @@ fun LinkCard(
                 .fillMaxWidth()
                 .heightIn(max = 85.dp)
         ) {
-            if (!isBig) {
+            if (!isBig) { // Image is displayed as a square on the side when not landscape
                 AsyncImage(
                     model = imageRequest,
                     contentDescription = null,

app/src/main/java/xyz/wingio/dimett/ui/widgets/posts/Poll.kt

@@ -32,17 +32,36 @@ import xyz.wingio.dimett.ui.components.Text
 import xyz.wingio.dimett.utils.getString
 import xyz.wingio.dimett.utils.toEmojiMap
 
+/**
+ * Allows users to vote for one or more options
+ */
 @Composable
 @OptIn(ExperimentalFoundationApi::class)
 fun Poll(
     poll: Poll,
     onVote: (String, List<Int>) -> Unit = { _, _ -> }
 ) {
-    val emojiMap = poll.emojis.toEmojiMap()
-    val selected = remember {
-        val l = mutableStateListOf<Int>()
-        l.addAll(poll.ownVotes)
-        l
+    val emojiMap = remember(poll) { poll.emojis.toEmojiMap() }
+    val selected = remember(poll) {
+        mutableStateListOf<Int>().apply {
+            addAll(poll.ownVotes)
+        }
+    }
+
+    /**
+     * Updates the currently selected options
+     */
+    fun select(optionIndex: Int, voted: Boolean) {
+        if (!poll.multiple) { // Only select one item at a time
+            selected.clear()
+            selected.add(optionIndex)
+        }
+
+        if (voted && poll.multiple) {
+            selected.remove(optionIndex) // Unselect when selected
+        } else {
+            selected.add(optionIndex)
+        }
     }
 
     Column(
@@ -51,26 +70,14 @@ fun Poll(
         for (i in poll.options.indices) {
             val option = poll.options[i]
             val voted = selected.contains(i)
-            val vote = {
-                if (!poll.multiple) {
-                    selected.clear()
-                    selected.add(i)
-                }
-
-                if (voted && poll.multiple) {
-                    selected.remove(i)
-                } else {
-                    selected.add(i)
-                }
-            }
 
             Row(
                 verticalAlignment = Alignment.CenterVertically,
                 modifier = Modifier
                     .shadow(3.dp, RoundedCornerShape(10.dp))
                     .clip(RoundedCornerShape(10.dp))
                     .clickable {
-                        vote()
+                        select(i, voted)
                     }
                     .background(MaterialTheme.colorScheme.surfaceColorAtElevation(2.dp))
                     .padding(12.dp)
@@ -90,7 +97,7 @@ fun Poll(
                 RadioButton(
                     selected = voted,
                     onClick = {
-                        vote()
+                        select(i, voted)
                     },
                     modifier = Modifier
                         .weight(0.25f)

app/src/main/java/xyz/wingio/dimett/ui/widgets/posts/Post.kt

@@ -11,6 +11,7 @@ import androidx.compose.material3.LocalContentColor
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.Surface
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.remember
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.res.stringResource
@@ -29,8 +30,20 @@ import xyz.wingio.dimett.utils.shareText
 import xyz.wingio.dimett.utils.toEmojiMap
 import xyz.wingio.dimett.utils.toMentionMap
 
-@Suppress("LocalVariableName")
+/**
+ * Post displayed in a feed
+ *
+ * @param post Information about the post
+ * @param onAvatarClick Called when the authors avatar is clicked
+ * @param onMentionClick Called when any mention (@user or @user@domain) is clicked
+ * @param onHashtagClick Called when a hashtag (#tag) is clicked
+ * @param onReplyClick Called when the reply button is pressed
+ * @param onFavoriteClick Called when the favorite button is pressed
+ * @param onBoostClick Called when the boost button is pressed
+ * @param onVotedInPoll Called when the user submits their selection in a poll
+ */
 @Composable
+@Suppress("LocalVariableName")
 fun Post(
     post: Post,
     onAvatarClick: (String) -> Unit = {},
@@ -42,13 +55,15 @@ fun Post(
     onVotedInPoll: (String, List<Int>) -> Unit = { _, _ -> }
 ) {
     val ctx = LocalContext.current
-    val _post = post.boosted ?: post
-    val timeString = DateUtils.getRelativeTimeSpanString(
-        /* time = */ post.createdAt.toEpochMilliseconds(),
-        /* now = */ System.currentTimeMillis(),
-        /* minResolution = */ 0L,
-        /* flags = */ DateUtils.FORMAT_ABBREV_ALL
-    ).toString()
+    val _post = post.boosted ?: post // The actually displayed post, not the same if its a boost
+    val timeString = remember(post.createdAt) {
+        DateUtils.getRelativeTimeSpanString(
+            /* time = */ post.createdAt.toEpochMilliseconds(),
+            /* now = */ System.currentTimeMillis(),
+            /* minResolution = */ 0L,
+            /* flags = */ DateUtils.FORMAT_ABBREV_ALL
+        ).toString()
+    }
 
     Surface(
         modifier = Modifier.fillMaxWidth(),
@@ -137,7 +152,7 @@ fun Post(
             }
 
             _post.card?.let {
-                if (_post.media.isEmpty()) {
+                if (_post.media.isEmpty()) { // We don't want to show both the media and card at the same time, too big
                     Card(
                         card = it
                     )

app/src/main/java/xyz/wingio/dimett/ui/widgets/posts/PostAuthor.kt

@@ -24,6 +24,16 @@ import xyz.wingio.dimett.ast.render
 import xyz.wingio.dimett.ui.components.BadgedItem
 import xyz.wingio.dimett.ui.components.Text
 
+/**
+ * Displays the avatar along with display name and username for a post's author
+ *
+ * @param avatarUrl Url pointing to the authors avatar
+ * @param displayName Authors display name
+ * @param acct The username of the author (@user or @[email protected])
+ * @param emojis The emojis present in the display name
+ * @param bot Whether or not the author is an automated account
+ * @param onAvatarClick Callback for when the avatar is clicked
+ */
 @Composable
 fun PostAuthor(
     avatarUrl: String,

app/src/main/java/xyz/wingio/dimett/ui/widgets/posts/PostButtons.kt

@@ -33,6 +33,19 @@ import xyz.wingio.dimett.R
 import xyz.wingio.dimett.ui.components.Text
 import xyz.wingio.dimett.utils.formatNumber
 
+/**
+ * Set of buttons and their interaction counts
+ *
+ * @param replies Number of replies to the post
+ * @param favorites Number of people that favorited this post
+ * @param boosts Number of people that boosted this post
+ * @param boosted Whether the current user has boosted this post
+ * @param favorited Whether the current user has favorited this post
+ * @param onReplyClick Called when the reply button is pressed
+ * @param onFavoriteClick Called when the favorite button is pressed
+ * @param onBoostClick Called when the boost button is pressed
+ * @param onShareClick Called when the share button is pressed
+ */
 @Composable
 @OptIn(ExperimentalLayoutApi::class)
 fun PostButtons(
@@ -78,6 +91,14 @@ fun PostButtons(
     }
 }
 
+/**
+ * Version of [TextButton][androidx.compose.material3.TextButton] with an icon
+ *
+ * @param icon Icon displayed next to the label
+ * @param contentDescription Describes the button for screen readers
+ * @param text Label to be displayed in the button
+ * @param onClick Called when the button is clicked
+ */
 @Composable
 fun PostButton(
     icon: ImageVector,

app/src/main/java/xyz/wingio/dimett/ui/widgets/posts/PostInfoBar.kt

@@ -18,6 +18,9 @@ import androidx.compose.ui.text.AnnotatedString
 import androidx.compose.ui.unit.dp
 import xyz.wingio.dimett.ui.components.Text
 
+/**
+ * Displays some additional information about a post
+ */
 @Composable
 fun PostInfoBar(
     icon: ImageVector,
@@ -29,17 +32,16 @@ fun PostInfoBar(
         verticalAlignment = Alignment.CenterVertically
     ) {
         Spacer(
-            Modifier.width(10.dp)
+            Modifier.width(10.dp) // Push to the side a little bit to line the space up with the avatar in a post
         )
         Icon(
             imageVector = icon,
             contentDescription = stringResource(iconDescription),
             modifier = Modifier.size(18.dp)
         )
-        ProvideTextStyle(MaterialTheme.typography.labelSmall) {
-            Text(
-                text = text
-            )
-        }
+        Text(
+            text = text,
+            style = MaterialTheme.typography.labelSmall
+        )
     }
 }