From 04e4ea82edd7e3f51da5d8a026c61c78b83ad53e Mon Sep 17 00:00:00 2001 From: Alexander Capehart Date: Mon, 17 Mar 2025 13:53:56 -0600 Subject: [PATCH] musikr: cleanup docs --- .../org/oxycblt/musikr/cache/db/DBCache.kt | 14 ++++++++------ .../java/org/oxycblt/musikr/covers/Covers.kt | 5 +++-- .../musikr/covers/chained/ChainedCovers.kt | 6 ++++-- .../musikr/covers/embedded/EmbeddedCovers.kt | 4 ++-- .../org/oxycblt/musikr/covers/fs/FSCovers.kt | 6 ++++++ .../musikr/covers/stored/CoverStorage.kt | 10 ++++++++++ .../musikr/covers/stored/StoredCovers.kt | 18 ++++++++++++------ .../musikr/covers/stored/Transcoding.kt | 14 ++++++++------ 8 files changed, 53 insertions(+), 24 deletions(-) diff --git a/musikr/src/main/java/org/oxycblt/musikr/cache/db/DBCache.kt b/musikr/src/main/java/org/oxycblt/musikr/cache/db/DBCache.kt index 6bc5f521d..6835dd40b 100644 --- a/musikr/src/main/java/org/oxycblt/musikr/cache/db/DBCache.kt +++ b/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 - * singleton, since it implicitly holds a Room database. As a result, you should only create - * EITHER a [DBCache] or a [MutableDBCache]. + * Create a new instance of [DBCache] from the given [context]. + * + * 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 - * be a singleton, since it implicitly holds a Room database. As a result, you should only - * create EITHER a [DBCache] or a [MutableDBCache]. + * Create a new instance of [MutableDBCache] from the given [context]. + * + * 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]. diff --git a/musikr/src/main/java/org/oxycblt/musikr/covers/Covers.kt b/musikr/src/main/java/org/oxycblt/musikr/covers/Covers.kt index 46e7d0193..aeb9b103c 100644 --- a/musikr/src/main/java/org/oxycblt/musikr/covers/Covers.kt +++ b/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 - * is explicitly stored on-device somewhere. + * A cover that can be opened as a [ParcelFileDescriptor]. + * + * This more or less implies that the cover is explicitly stored on-device somewhere. */ interface FDCover : Cover { /** diff --git a/musikr/src/main/java/org/oxycblt/musikr/covers/chained/ChainedCovers.kt b/musikr/src/main/java/org/oxycblt/musikr/covers/chained/ChainedCovers.kt index 7c8ffc78b..388c183a8 100644 --- a/musikr/src/main/java/org/oxycblt/musikr/covers/chained/ChainedCovers.kt +++ b/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(vararg many: Covers) : Covers { * * 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(vararg many: MutableCovers) : MutableCovers { diff --git a/musikr/src/main/java/org/oxycblt/musikr/covers/embedded/EmbeddedCovers.kt b/musikr/src/main/java/org/oxycblt/musikr/covers/embedded/EmbeddedCovers.kt index 0be363846..86f9bec94 100644 --- a/musikr/src/main/java/org/oxycblt/musikr/covers/embedded/EmbeddedCovers.kt +++ b/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 - * embedded cover repository. + * You are best to compose this with [org.oxycblt.musikr.covers.stored.MutableStoredCovers] to get + * a full embedded cover repository. * * @param coverIdentifier The [CoverIdentifier] to use to create identifiers for the cover data. */ diff --git a/musikr/src/main/java/org/oxycblt/musikr/covers/fs/FSCovers.kt b/musikr/src/main/java/org/oxycblt/musikr/covers/fs/FSCovers.kt index f10701427..3322ae8ef 100644 --- a/musikr/src/main/java/org/oxycblt/musikr/covers/fs/FSCovers.kt +++ b/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 { @@ -76,11 +79,14 @@ class FSCovers(private val context: Context) : Covers { /** * 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 { diff --git a/musikr/src/main/java/org/oxycblt/musikr/covers/stored/CoverStorage.kt b/musikr/src/main/java/org/oxycblt/musikr/covers/stored/CoverStorage.kt index 04552e153..289f2df21 100644 --- a/musikr/src/main/java/org/oxycblt/musikr/covers/stored/CoverStorage.kt +++ b/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" } diff --git a/musikr/src/main/java/org/oxycblt/musikr/covers/stored/StoredCovers.kt b/musikr/src/main/java/org/oxycblt/musikr/covers/stored/StoredCovers.kt index 081222e8e..4b649e734 100644 --- a/musikr/src/main/java/org/oxycblt/musikr/covers/stored/StoredCovers.kt +++ b/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 - * instance is [Transcoding]-agnostic, it will yield a cover as long as it exists somewhere in the - * given storage. + * A [Covers] implementation for stored covers in the backing [CoverStorage]. + * + * 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 { } /** - * A [MutableCovers] implementation for stored covers in the backing [CoverStorage]. This will open - * whatever cover data is yielded by [src], and then write it to the [coverStorage] using the - * whatever [transcoding] is provided. + * A [MutableCovers] implementation for stored covers in the backing [CoverStorage]. + * + * 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]. diff --git a/musikr/src/main/java/org/oxycblt/musikr/covers/stored/Transcoding.kt b/musikr/src/main/java/org/oxycblt/musikr/covers/stored/Transcoding.kt index 857149544..5f957827b 100644 --- a/musikr/src/main/java/org/oxycblt/musikr/covers/stored/Transcoding.kt +++ b/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 - * 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 - * that large or malformed data may be written to [CoverStorage] and yield bad results when loading - * the resulting covers. + * A [Transcoding] implementation that does not transcode the cover data at all. + * + * 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 that large or malformed data may + * 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.