all: trim comments

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: mmarca-tech

app/build.gradle

@@ -43,8 +43,7 @@ android {
     buildTypes {
         debug {
             applicationIdSuffix ".debug"
-            // Suffix with the abbreviated commit so any crash report self-identifies which
-            // build produced it -- line numbers in stack traces are useless without that.
+            // Include the commit so crash reports self-identify their build.
             versionNameSuffix "-DEBUG-" + ("git rev-parse --short HEAD".execute([], rootDir).text.trim() ?: "unknown")
         }
 

app/src/main/java/org/oxycblt/auxio/image/coil/CoilModule.kt

@@ -61,21 +61,14 @@ class CoilModule {
             .transitionFactory(ErrorCrossfadeTransitionFactory())
             // Not downloading anything, so no disk-caching
             .diskCachePolicy(CachePolicy.DISABLED)
-            // Coil defaults both of these to Dispatchers.IO, which is 64 threads wide. Scrolling
-            // a large library queues a cover request per row as it flies past, so that default
-            // lets dozens of decodes run at once and take every core with them -- the UI thread
-            // then misses its frame deadline by hundreds of milliseconds even though no
-            // individual decode is slow. Bound the whole pipeline instead. Both stages share one
-            // limiter so this caps total concurrent cover work, not each stage separately.
+            // Coil defaults these to Dispatchers.IO (64 threads), which lets fast scrolling
+            // saturate every core with cover decodes and starve the UI thread. One shared
+            // limiter caps total concurrent cover work.
             .fetcherCoroutineContext(coverDispatcher)
             .decoderCoroutineContext(coverDispatcher)
             .build()
 
     private companion object {
-        /**
-         * Leave at least half the cores for everything else, and never go wide enough that cover
-         * work can crowd out the UI thread on a big device.
-         */
         val coverDispatcher =
             Dispatchers.IO.limitedParallelism(
                 (Runtime.getRuntime().availableProcessors() / 2).coerceIn(2, 4)

app/src/main/java/org/oxycblt/auxio/image/coil/CoverCompositionFetcher.kt

@@ -108,10 +108,8 @@ abstract class CoverCompositionFetcher(
     }
 
     /**
-     * Find the largest power-of-two downscale that keeps the cover at or above [target] pixels on
-     * its shorter edge. A composition never draws a source cover larger than the composition
-     * itself, so decoding beyond that is wasted heap -- and covers can be several thousand pixels
-     * wide, which is enough to exhaust the heap once four of them are held at once.
+     * The largest power-of-two downscale keeping the cover at or above [target] pixels. Four
+     * full-resolution covers held at once is enough to exhaust the heap.
      */
     private fun calculateInSampleSize(width: Int, height: Int, target: Int): Int {
         if (width <= 0 || height <= 0) return 1

app/src/main/java/org/oxycblt/auxio/list/recycler/FastScrollRecyclerView.kt

@@ -285,11 +285,8 @@ constructor(context: Context, attrs: AttributeSet? = null, @AttrRes defStyleAttr
 
     var listener: Listener? = null
 
-    // onPreDraw runs from an ItemDecoration, so it fires on every draw pass of the list --
-    // scrolling or not. Deriving the popup text is not free (it re-reads the current sort out of
-    // SharedPreferences, and depending on the sort allocates a Calendar or an ICU MeasureFormat),
-    // so memoize it against the item it was derived from. The text only changes when the item
-    // under the thumb does.
+    // Deriving popup text is not free and onPreDraw runs on every draw pass, so memoize it
+    // against the position it was derived from.
     private var popupDataPos = NO_POSITION
     private var popupDataText: String? = null
 
@@ -457,11 +454,6 @@ constructor(context: Context, attrs: AttributeSet? = null, @AttrRes defStyleAttr
         invalidatePopupData()
     }
 
-    /**
-     * Drop the memoized popup text so that it is re-derived on the next draw. Must be called
-     * whenever the item at a given position may have changed, since the memo is keyed on position
-     * alone.
-     */
     private fun invalidatePopupData() {
         popupDataPos = NO_POSITION
         popupDataText = null
@@ -578,24 +570,17 @@ constructor(context: Context, attrs: AttributeSet? = null, @AttrRes defStyleAttr
             return
         }
         val dy = newOffsetY - previousOffsetY
-        // scrollBy makes the layout manager walk the requested distance one item at a time,
-        // binding and laying out every row it passes over. That is fine for the small deltas a
-        // slow drag produces, but a pixel of thumb travel maps to hundreds of pixels of content
-        // on a library-sized list, so a single touch event can end up laying out thousands of
-        // rows before the frame is even allowed to start. Past a couple of screenfuls, jump
-        // straight to the target row instead of walking there.
+        // scrollBy lays out every row it travels past, which on a large list can be thousands of
+        // rows in one touch event. Past a couple of screenfuls, jump instead of walking.
         if (abs(dy) > height * MAX_SCROLL_BY_SCREENS && jumpToOffset(newOffsetY)) {
             return
         }
         scrollBy(0, max(dy.roundToInt(), -computeVerticalScrollOffset()))
     }
 
     /**
-     * Jump directly to the row nearest [offsetY], skipping everything in between.
-     *
-     * This is an estimate off the average laid-out row height, in the same spirit as the scroll
-     * range the thumb position itself is derived from. Returns false if there is nothing laid out
-     * to estimate from, in which case the caller should fall back to an incremental scroll.
+     * Jump directly to the row nearest [offsetY], estimated off the average laid-out row height.
+     * Returns false if there is nothing laid out to estimate from.
      */
     private fun jumpToOffset(offsetY: Float): Boolean {
         val layoutManager = layoutManager as? LinearLayoutManager ?: return false
@@ -616,7 +601,6 @@ constructor(context: Context, attrs: AttributeSet? = null, @AttrRes defStyleAttr
         return true
     }
 
-    /** The average height of the currently laid-out children, or 0 if there are none. */
     private fun averageRowHeight(): Int {
         val childCount = childCount
         if (childCount == 0) {

app/src/main/java/org/oxycblt/auxio/playback/PlaybackUtil.kt

@@ -63,12 +63,7 @@ fun Long.formatDurationMs(isElapsed: Boolean) = msToSecs().formatDurationSecs(is
 private var popupDurationLocale: Locale? = null
 private var popupDurationFormat: MeasureFormat? = null
 
-/**
- * The [MeasureFormat] used by [formatDurationMsPopup], memoized against the current locale.
- *
- * Building one is expensive enough to matter here, since fast-scrolling asks for a new popup string
- * every time the item under the thumb changes.
- */
+/** The [MeasureFormat] used by [formatDurationMsPopup], memoized against the current locale. */
 private fun popupDurationFormat(): MeasureFormat {
     val locale = Locale.getDefault()
     var format = popupDurationFormat

app/src/main/java/org/oxycblt/auxio/playback/service/ExoPlaybackStateHolder.kt

@@ -88,30 +88,15 @@ class ExoPlaybackStateHolder(
     private var currentSaveJob: Job? = null
     private var openAudioEffectSession = false
 
-    // --- QUEUE STATE ---
-    // The queue is owned HERE, not by ExoPlayer. Handing the player a MediaItem per queue entry
-    // does not scale: every item costs a MediaItem plus several player-internal holder objects,
-    // which at library scale (a 40k-song "play from all" queue) measures out to ~77MB of Java
-    // heap and transiently doubles on every reshuffle -- enough to exhaust the standard 256MB
-    // heap once the library model itself is accounted for. Instead the player only ever holds a
-    // small window of items around the current song (see below), and these fields are the source
-    // of truth that resolveQueue() snapshots for the rest of the app.
-    //
-    // The representation mirrors RawQueue: heap is the queue in unshuffled order, mapping remaps
-    // resolved positions to heap indices when shuffled (empty otherwise), and heapIndex is the
-    // heap position of the current song.
+    // The queue is owned here rather than by ExoPlayer, since a MediaItem per queue entry does
+    // not scale to library-sized queues. The representation mirrors RawQueue.
     private val heap = mutableListOf<Song>()
     private val mapping = mutableListOf<Int>()
     private var heapIndex = -1
-
-    // The player no longer sees the full queue, so its repeat mode can't represent ALL on a
-    // windowed queue and the app's repeat mode must be held here (see syncPlayerRepeatMode).
     private var repeatModeState = RepeatMode.NONE
 
-    // The player's current playlist, as resolved queue positions: the player's item i is the
-    // queue's window[i]-th song in playback order. Kept contiguous (circularly contiguous when
-    // wrapping under RepeatMode.ALL) and always containing the current song with margin on both
-    // sides, so gapless preloading of the next song keeps working.
+    // The player's playlist as resolved queue positions, a small contiguous run around the
+    // current song. Wraps circularly under RepeatMode.ALL.
     private val window = ArrayDeque<Int>()
 
     var sessionOngoing = false
@@ -244,8 +229,7 @@ class ExoPlaybackStateHolder(
         repeatModeState = repeatMode
         syncPlayerRepeatMode()
         updatePauseOnRepeat()
-        // The repeat mode decides whether the window wraps around the queue edges, so it may
-        // need to be reshaped.
+        // The repeat mode decides whether the window wraps, so it may need to be reshaped.
         slideWindow()
         playbackManager.ack(this, StateAck.RepeatModeChanged)
         deferSave()
@@ -284,7 +268,6 @@ class ExoPlaybackStateHolder(
         }
         mapping.clear()
         if (shuffled) {
-            // Anchor the current song to the front of the new shuffled order.
             mapping.addAll(shuffledMapping(anchor = heapIndex))
         }
         syncPlayerRepeatMode()
@@ -350,13 +333,11 @@ class ExoPlaybackStateHolder(
         val insertAt = heapIndex + 1
         heap.addAll(insertAt, songs)
         if (isShuffled) {
-            // Inserting into the heap shifted every heap index at or above the insertion point.
             for (i in mapping.indices) {
                 if (mapping[i] >= insertAt) {
                     mapping[i] += songs.size
                 }
             }
-            // Then place the new songs directly after the current position in play order.
             mapping.addAll(resolvedIndex() + 1, List(songs.size) { insertAt + it })
         }
         refreshWindow()
@@ -383,7 +364,6 @@ class ExoPlaybackStateHolder(
             return
         }
         if (isShuffled) {
-            // Play order is defined by the mapping; the heap (and thus heapIndex) is untouched.
             mapping.add(to, mapping.removeAt(from))
         } else {
             heap.add(to, heap.removeAt(from))
@@ -425,8 +405,7 @@ class ExoPlaybackStateHolder(
                 player.clearMediaItems()
             }
             songWillChange -> {
-                // Match ExoPlayer's own removal behavior: playback moves to the song that now
-                // occupies the removed song's position (or the last song if it was the tail).
+                // Playback moves to the song now occupying the removed song's position.
                 heapIndex = heapIndexAt(at.coerceAtMost(heap.size - 1))
                 hardResetWindow()
             }
@@ -544,7 +523,6 @@ class ExoPlaybackStateHolder(
             return (0 until size).toList()
         }
         return if (repeatModeState == RepeatMode.ALL) {
-            // Positions stay unique because the window is strictly smaller than the queue.
             (center - WINDOW_RADIUS..center + WINDOW_RADIUS).map { ((it % size) + size) % size }
         } else {
             val start = (center - WINDOW_RADIUS).coerceAtLeast(0)
@@ -572,7 +550,7 @@ class ExoPlaybackStateHolder(
             }
     }
 
-    /** Replace the playlist outright, (re)starting playback of the current song. */
+    /** Replace the playlist outright, (re)starting the current song. */
     private fun hardResetWindow() {
         val desired = computeWindowPositions(resolvedIndex())
         window.clear()
@@ -585,11 +563,7 @@ class ExoPlaybackStateHolder(
         player.seekTo(desired.indexOf(resolvedIndex()), C.TIME_UNSET)
     }
 
-    /**
-     * Rebuild the playlist around the currently-playing item after a queue mutation, without
-     * interrupting it. The songs behind the window's positions may have changed, so everything
-     * except the current item is replaced.
-     */
+    /** Rebuild the playlist around the currently-playing item without interrupting it. */
     private fun refreshWindow() {
         val current = resolvedIndex()
         val desired = computeWindowPositions(current)
@@ -600,7 +574,6 @@ class ExoPlaybackStateHolder(
         }
         val playing = player.currentMediaItem?.song
         if (playing == null || playing != heap.getOrNull(heapIndex)) {
-            // Player is empty or out of sync with our state; start over.
             hardResetWindow()
             return
         }
@@ -639,8 +612,7 @@ class ExoPlaybackStateHolder(
             return
         }
         val desiredSet = desired.toHashSet()
-        // Trim stale edges. This can never remove the current item, since the window is always
-        // computed around it.
+        // Never removes the current item, since the window is always computed around it.
         while (window.isNotEmpty() && window.first() !in desiredSet) {
             player.removeMediaItem(0)
             window.removeFirst()
@@ -671,7 +643,7 @@ class ExoPlaybackStateHolder(
         }
     }
 
-    /** Adopt the player's current item as the current song after the player moved on its own. */
+    /** Adopt the player's current item after the player moved on its own. */
     private fun syncIndexFromPlayer() {
         val resolved = window.getOrNull(player.currentMediaItemIndex) ?: return
         heapIndex = heapIndexAt(resolved)

app/src/main/java/org/oxycblt/auxio/playback/service/MediaSessionHolder.kt

@@ -101,8 +101,7 @@ private constructor(
     val notification: ForegroundServiceNotification
         get() = _notification
 
-    // The bounds of the queue window currently published to the media session, as absolute
-    // indices into the full queue.
+    // Bounds of the queue window currently published, as absolute queue indices.
     private var queueWindowStart = 0
     private var queueWindowEnd = 0
 
@@ -137,9 +136,7 @@ private constructor(
 
     override fun onIndexMoved(index: Int) {
         updateMediaMetadata(playbackManager.currentSong, playbackManager.parent)
-        // Only a window of the queue is published, so it has to follow playback as the index
-        // walks out of it. If the whole queue already fits, the window never changes and this
-        // does nothing.
+        // The published queue window has to follow playback as the index walks out of it.
         val queue = playbackManager.queue
         if (
             max(0, index - QUEUE_WINDOW_RADIUS) != queueWindowStart ||
@@ -327,12 +324,9 @@ private constructor(
      * @param queue The current queue to upload.
      */
     private fun updateQueue(queue: List<Song>, index: Int) {
-        // setQueue marshals the entire list into a Parcel and hands it to the system, and each
-        // item first has to have its description resolved (several strings, a Uri and a Bundle
-        // apiece). Doing that for a library-sized queue blocks the main thread for seconds and
-        // risks TransactionTooLargeException. Consumers of this queue (Android Auto, bluetooth
-        // head units) only ever show a handful of surrounding items, so publish a window around
-        // the current song instead of the whole thing.
+        // setQueue parcels the whole list to the system, which for a library-sized queue blocks
+        // the main thread for seconds and risks TransactionTooLargeException. Publish a window
+        // around the current song instead.
         val start = max(0, index - QUEUE_WINDOW_RADIUS)
         val end = min(queue.size, index + QUEUE_WINDOW_RADIUS + 1)
         val queueItems =
@@ -342,9 +336,7 @@ private constructor(
                         context,
                         { putInt(MediaSessionInterface.KEY_QUEUE_POS, i) },
                     )
-                // Store the item index so we can then use the analogous index in the
-                // playback state. This stays absolute so that skip-to-item and queue item
-                // removal still address the right song.
+                // Ids stay absolute so skip-to-item still addresses the right song.
                 MediaSessionCompat.QueueItem(description, i.toLong())
             }
         queueWindowStart = start

app/src/main/java/org/oxycblt/auxio/widgets/WidgetComponent.kt

@@ -119,13 +119,9 @@ private constructor(
                         }
                     }
 
-                    // Never ORIGINAL here. This bitmap ends up in a RemoteViews that has to be
-                    // marshalled to the launcher, and the widget draws it at a couple of hundred
-                    // pixels at most, so decoding native-resolution art wastes a large amount of
-                    // memory and CPU per update -- and update() runs on nearly every playback
-                    // event, including progression changes. The corner radius applied below is an
-                    // absolute pixel value sized for the widget, so bounding the bitmap also
-                    // makes that radius land at roughly the intended proportion.
+                    // Bounded, not ORIGINAL: this bitmap is marshalled into a RemoteViews and
+                    // drawn at a couple hundred pixels, and update() runs on nearly every
+                    // playback event.
                     return builder.size(COVER_MAX_PX, COVER_MAX_PX).transformations(transformations)
                 }
 
@@ -195,11 +191,6 @@ private constructor(
     )
 
     private companion object {
-        /**
-         * Upper bound for the cover bitmap handed to the widget. Comfortably above any widget cover
-         * a phone will actually draw, and 1MB as ARGB_8888 rather than the tens of MB a
-         * native-resolution decode can reach.
-         */
         const val COVER_MAX_PX = 512
     }
 }

musikr/src/main/java/org/oxycblt/musikr/cache/db/DBCache.kt

@@ -41,12 +41,8 @@ class DBCache private constructor(private val readDao: CacheReadDao) : Cache {
     private val mappingLock = Mutex()
 
     /**
-     * Drop the in-memory copy of the cache table.
-     *
-     * [read] memoizes the entire table so that a load doesn't issue a query per file, but that copy
-     * holds every tag of every song and is only useful while a load is in progress. Holding it for
-     * the lifetime of the process is a second, complete copy of the library's metadata sitting
-     * alongside the library itself, which is enough to exhaust the heap on large libraries.
+     * Drop the in-memory copy of the cache table. It is only useful while a load is in progress,
+     * and holding it longer duplicates the entire library's metadata in memory.
      */
     suspend fun release() {
         mappingLock.withLock { mapping = null }
@@ -166,7 +162,6 @@ private constructor(private val inner: DBCache, private val writeDao: CacheWrite
 
     override suspend fun cleanup(excluding: List<CachedFile>) {
         writeDao.deleteExcludingUris(excluding.mapTo(mutableSetOf()) { it.file.uri.toString() })
-        // Cleanup terminates a load, so the read mapping is dead weight from here on.
         inner.release()
     }