musikr: cleanup docs

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

@@ -72,9 +72,10 @@ class DBCache private constructor(private val readDao: CacheReadDao) : Cache {
 
     companion object {
         /**
-         * Create a new instance of [DBCache] from the given [context]. This instance should be a
+         * Create a new instance of [DBCache] from the given [context].
-         * singleton, since it implicitly holds a Room database. As a result, you should only create
+         *
-         * EITHER a [DBCache] or a [MutableDBCache].
+         * This instance should be a singleton, since it implicitly holds a Room database. As a
+         * result, you should only create EITHER a [DBCache] or a [MutableDBCache].
          *
          * @param context The context to use to create the Room database.
          * @return A new instance of [DBCache].
@@ -135,9 +136,10 @@ private constructor(private val inner: DBCache, private val writeDao: CacheWrite
 
     companion object {
         /**
-         * Create a new instance of [MutableDBCache] from the given [context]. This instance should
+         * Create a new instance of [MutableDBCache] from the given [context].
-         * be a singleton, since it implicitly holds a Room database. As a result, you should only
+         *
-         * create EITHER a [DBCache] or a [MutableDBCache].
+         * This instance should be a singleton, since it implicitly holds a Room database. As a
+         * result, you should only create EITHER a [DBCache] or a [MutableDBCache].
          *
          * @param context The context to use to create the Room database.
          * @return A new instance of [MutableDBCache].

musikr/src/main/java/org/oxycblt/musikr/covers/Covers.kt

@@ -120,8 +120,9 @@ interface Cover {
 }
 
 /**
- * A cover that can be opened as a [ParcelFileDescriptor]. This more or less implies that the cover
+ * A cover that can be opened as a [ParcelFileDescriptor].
- * is explicitly stored on-device somewhere.
+ *
+ * This more or less implies that the cover is explicitly stored on-device somewhere.
  */
 interface FDCover : Cover {
     /**

musikr/src/main/java/org/oxycblt/musikr/covers/chained/ChainedCovers.kt

@@ -32,8 +32,9 @@ import org.oxycblt.musikr.metadata.Metadata
  * then filesystem-based covers.
  *
  * This implementation will return the first hit from the provided [Covers] instances.
+ * It's assumed that there is no ID overlap between [Covers] outputs.
  *
- * It's assumed that there is no ID overlap between [MutableCovers] outputs.
+ * See [MutableChainedCovers] for the mutable variant.
  *
  * @param many The [Covers] instances to chain together.
  */
@@ -59,9 +60,10 @@ class ChainedCovers<R : Cover, T : R>(vararg many: Covers<out T>) : Covers<R> {
  *
  * This implementation will use the first hit from the provided [MutableCovers] instances, and
  * propagate cleanup across all [MutableCovers] instances.
- *
  * It's assumed that there is no ID overlap between [MutableCovers] outputs.
  *
+ * See [ChainedCovers] for the immutable variant.
+ *
  * @param many The [MutableCovers] instances to chain together.
  */
 class MutableChainedCovers<R : Cover, T : R>(vararg many: MutableCovers<out T>) : MutableCovers<R> {

musikr/src/main/java/org/oxycblt/musikr/covers/embedded/EmbeddedCovers.kt

@@ -36,8 +36,8 @@ import org.oxycblt.musikr.metadata.Metadata
  * - Covers generated by this implementation will take up large amounts of memory, more or less
  *   guaranteeing an OOM error if used with a large library.
  *
- * You are best to compose this with [org.oxycblt.musikr.covers.stored.StoredCovers] to get a full
+ * You are best to compose this with [org.oxycblt.musikr.covers.stored.MutableStoredCovers] to get
- * embedded cover repository.
+ * a full embedded cover repository.
  *
  * @param coverIdentifier The [CoverIdentifier] to use to create identifiers for the cover data.
  */

musikr/src/main/java/org/oxycblt/musikr/covers/fs/FSCovers.kt

@@ -39,11 +39,14 @@ private const val PREFIX = "mcf:"
 
 /**
  * A [Covers] implementation that obtains cover art from the filesystem, such as cover.jpg.
+ *
  * Cover.jpg is pretty widely used in music libraries to save space, so it's good to use this.
  *
  * This implementation does not search the directory tree given that it cannot access it. Rather, it
  * assumes the provided id ius one yielded by [MutableFSCovers].
  *
+ * See [MutableFSCovers] for the mutable variant.
+ *
  * @param context The [Context] to use to access the filesystem and check for ID validity.
  */
 class FSCovers(private val context: Context) : Covers<FDCover> {
@@ -76,11 +79,14 @@ class FSCovers(private val context: Context) : Covers<FDCover> {
 
 /**
  * A [MutableCovers] implementation that obtains cover art from the filesystem, such as cover.jpg.
+ *
  * Cover.jpg is pretty widely used in music libraries to save space, so it's good to use this.
  *
  * This implementation will search the parent directory for the best cover art. "Best" being defined
  * as having cover-art-ish names and having a good format like png/jpg/webp.
  *
+ * See [FSCovers] for the immutable variant.
+ *
  * @param context The [Context] to use to access the filesystem and check for ID validity.
  */
 class MutableFSCovers(private val context: Context) : MutableCovers<FDCover> {

musikr/src/main/java/org/oxycblt/musikr/covers/stored/CoverStorage.kt

@@ -70,6 +70,16 @@ interface CoverStorage {
     suspend fun rm(name: String)
 
     companion object {
+        /**
+         * Create a [CoverStorage] implementation at some directory. Covers will be written
+         * in that location.
+         *
+         * Note that in the context of Android's scoped storage, the given [File] will need to be
+         * in the app's internal storage
+         *
+         * @param dir The directory to store the covers in.
+         * @return A [CoverStorage] instance.
+         */
         suspend fun at(dir: File): CoverStorage {
             withContext(Dispatchers.IO) {
                 if (dir.exists()) check(dir.isDirectory) { "Not a directory" }

musikr/src/main/java/org/oxycblt/musikr/covers/stored/StoredCovers.kt

@@ -30,9 +30,12 @@ import org.oxycblt.musikr.metadata.Metadata
 private const val PREFIX = "mcs:"
 
 /**
- * A [Covers] implementation for stored covers in the backing [CoverStorage]. Note that this
+ * A [Covers] implementation for stored covers in the backing [CoverStorage].
- * instance is [Transcoding]-agnostic, it will yield a cover as long as it exists somewhere in the
+ *
- * given storage.
+ * Note that this instance is [Transcoding]-agnostic, it will yield a cover as long as it exists
+ * somewhere in the given storage.
+ *
+ * See [MutableStoredCovers] for the mutable variant.
  *
  * @param coverStorage The [CoverStorage] to use to obtain the cover data.
  */
@@ -48,14 +51,17 @@ class StoredCovers(private val coverStorage: CoverStorage) : Covers<FDCover> {
 }
 
 /**
- * A [MutableCovers] implementation for stored covers in the backing [CoverStorage]. This will open
+ * A [MutableCovers] implementation for stored covers in the backing [CoverStorage].
- * whatever cover data is yielded by [src], and then write it to the [coverStorage] using the
+ *
- * whatever [transcoding] is provided.
+ * This will open whatever cover data is yielded by [src], and then write it to the [coverStorage]
+ * using the whatever [transcoding] is provided.
  *
  * This allows large in-memory covers yielded by [MutableCovers] to be cached in storage rather than
  * kept in memory. However, it can be used for any asynchronously fetched covers as well to save
  * time, such as ones obtained by network.
  *
+ * See [StoredCovers] for the immutable variant.
+ *
  * @param src The [MutableCovers] to use to obtain the cover data.
  * @param coverStorage The [CoverStorage] to use to write the cover data to.
  * @param transcoding The [Transcoding] to use to write the cover data to the [coverStorage].

musikr/src/main/java/org/oxycblt/musikr/covers/stored/Transcoding.kt

@@ -46,11 +46,11 @@ interface Transcoding {
 }
 
 /**
- * A [Transcoding] implementation that does not transcode the cover data at all, and simply writes
+ * A [Transcoding] implementation that does not transcode the cover data at all.
- * it to the output stream as-is. This is useful for when the cover data is already in the desired
+ *
- * format, or when the time/quality tradeoff of transcoding is not worth it. Note that this may mean
+ * This is useful for when the cover data is already in the desired format, or when the time/quality
- * that large or malformed data may be written to [CoverStorage] and yield bad results when loading
+ * tradeoff of transcoding is not worth it. Note that this may mean that large or malformed data may
- * the resulting covers.
+ * be written to [CoverStorage] and yield bad results when loading the resulting covers.
  */
 object NoTranscoding : Transcoding {
     override val tag = ".img"
@@ -62,7 +62,9 @@ object NoTranscoding : Transcoding {
 
 /**
  * A [Transcoding] implementation that compresses the cover data into a specific format, size, and
- * quality. This is useful if you want to standardize the covers to a specific format and minimize
+ * quality.
+ *
+ * This is useful if you want to standardize the covers to a specific format and minimize
  * the size of the cover data to save space.
  *
  * @param format The [Bitmap.CompressFormat] to use to compress the cover data.