chore(core): add kdoc for MediaSource

[skip ci]

Author: Wesley-Young

acidify-core/src/commonMain/kotlin/org/ntqqrev/acidify/common/ByteArrayMediaSource.kt

@@ -2,11 +2,19 @@ package org.ntqqrev.acidify.common
 
 import kotlinx.io.Buffer
 import kotlinx.io.RawSource
-
+import kotlin.js.JsExport
+
+/**
+ * 通过 [ByteArray] 构造的 [MediaSource] 实现。
+ * 该实现会直接使用提供的 [ByteArray] 作为数据源，因此在构造时需要保证该 [ByteArray] 不会被修改，以免导致数据不一致。
+ * 在调用 [readByteArray] 时会直接返回该 [ByteArray]。
+ */
+@JsExport
 class ByteArrayMediaSource(private val data: ByteArray) : MediaSource() {
     override val size: Long
         get() = data.size.toLong()
 
+    @JsExport.Ignore
     override fun openRawSource(): RawSource {
         return ByteArrayRawSource(data)
     }

acidify-core/src/commonMain/kotlin/org/ntqqrev/acidify/common/MediaSource.kt

@@ -5,20 +5,37 @@ import kotlinx.io.buffered
 import kotlinx.io.readByteArray
 import kotlin.js.JsExport
 
+/**
+ * 表示可重复使用、可释放的媒体资源
+ */
 @JsExport
 abstract class MediaSource {
+    /**
+     * 资源的体积
+     */
     abstract val size: Long
 
+    /**
+     * 打开一个全新的、用于访问该资源的 [RawSource] 实例
+     */
+    @JsExport.Ignore
     abstract fun openRawSource(): RawSource
 
-    abstract fun dispose()
-
+    /**
+     * 直接将该 [MediaSource] 的内容读取到一个 [ByteArray] 中。
+     */
     open fun readByteArray(): ByteArray {
         return openRawSource().buffered().use { source ->
             source.readByteArray()
         }
     }
 
+    /**
+     * 在资源使用完毕后释放该资源。
+     * 注意 `acidify-core` 的各个 API 都不会主动调用该方法，因此需要调用方主动释放资源。
+     */
+    abstract fun dispose()
+
     companion object {
         @JsExport.Ignore
         fun ByteArray.toMediaSource(): MediaSource = ByteArrayMediaSource(this)