From acd6b8ee8d4e18d39079703e96e91fce6348a6d1 Mon Sep 17 00:00:00 2001
From: Michele Pozzi <123.mpozzi@gmail.com>
Date: Wed, 18 Oct 2023 17:07:48 +0200
Subject: [PATCH] docs(bufferapi): add missing docs and improve formatting

---
 .../player/reactnative/BufferModule.kt        | 11 +++++--
 .../reactnative/converter/JsonConverter.kt    | 33 +++++++++++--------
 src/bufferApi.ts                              |  4 +--
 3 files changed, 30 insertions(+), 18 deletions(-)

diff --git a/android/src/main/java/com/bitmovin/player/reactnative/BufferModule.kt b/android/src/main/java/com/bitmovin/player/reactnative/BufferModule.kt
index 8e650d57..a7486999 100644
--- a/android/src/main/java/com/bitmovin/player/reactnative/BufferModule.kt
+++ b/android/src/main/java/com/bitmovin/player/reactnative/BufferModule.kt
@@ -11,6 +11,11 @@ private const val MODULE_NAME = "BufferModule"
 
 @ReactModule(name = MODULE_NAME)
 class BufferModule(private val context: ReactApplicationContext) : ReactContextBaseJavaModule(context) {
+    /**
+     * Collection of [BufferLevel] objects
+     * @param audio [BufferLevel] for [MediaType.Audio].
+     * @param video [BufferLevel] for [MediaType.Video].
+     */
     data class RNBufferLevels(val audio: BufferLevel, val video: BufferLevel)
 
     /**
@@ -19,9 +24,9 @@ class BufferModule(private val context: ReactApplicationContext) : ReactContextB
     override fun getName() = MODULE_NAME
 
     /**
-     * Gets the buffer level from the Player
-     * @param nativeId Native Id of the collector instance.
-     * @param type The type of buffer to return the level for.
+     * Gets the [buffer level][BufferLevel] from the Player
+     * @param nativeId Target player id.
+     * @param type The [type of buffer][JsonConverter.toBufferType] to return the level for.
      * @param promise JS promise object.
      */
     @ReactMethod
diff --git a/android/src/main/java/com/bitmovin/player/reactnative/converter/JsonConverter.kt b/android/src/main/java/com/bitmovin/player/reactnative/converter/JsonConverter.kt
index 01716e85..cac748ca 100644
--- a/android/src/main/java/com/bitmovin/player/reactnative/converter/JsonConverter.kt
+++ b/android/src/main/java/com/bitmovin/player/reactnative/converter/JsonConverter.kt
@@ -70,9 +70,9 @@ import java.util.UUID
 class JsonConverter {
     companion object {
         /**
-         * Converts an arbitrary `json` to `PlayerConfig`.
-         * @param json JS object representing the `PlayerConfig`.
-         * @return The generated `PlayerConfig` if successful, `null` otherwise.
+         * Converts an arbitrary `json` to [PlayerConfig].
+         * @param json JS object representing the [PlayerConfig].
+         * @return The generated [PlayerConfig] if successful, `null` otherwise.
          */
         @JvmStatic
         fun toPlayerConfig(json: ReadableMap?): PlayerConfig {
@@ -121,9 +121,9 @@ class JsonConverter {
         }
 
         /**
-         * Converts any JS object into a `BufferMediaTypeConfig` object.
-         * @param json JS object representing the `BufferMediaTypeConfig`.
-         * @return The generated `BufferMediaTypeConfig` if successful, `null` otherwise.
+         * Converts any JS object into a [BufferMediaTypeConfig] object.
+         * @param json JS object representing the [BufferMediaTypeConfig].
+         * @return The generated [BufferMediaTypeConfig] if successful, `null` otherwise.
          */
         @JvmStatic
         fun toBufferMediaTypeConfig(json: ReadableMap?): BufferMediaTypeConfig? {
@@ -138,9 +138,9 @@ class JsonConverter {
         }
 
         /**
-         * Converts any JS object into a `BufferConfig` object.
-         * @param json JS object representing the `BufferConfig`.
-         * @return The generated `BufferConfig` if successful, `null` otherwise.
+         * Converts any JS object into a [BufferConfig] object.
+         * @param json JS object representing the [BufferConfig].
+         * @return The generated [BufferConfig] if successful, `null` otherwise.
          */
         @JvmStatic
         fun toBufferConfig(json: ReadableMap?): BufferConfig? {
@@ -215,9 +215,9 @@ class JsonConverter {
         }
 
         /**
-         * Converts an arbitrary `json` to `SourceOptions`.
-         * @param json JS object representing the `SourceOptions`.
-         * @return The generated `SourceOptions`.
+         * Converts an arbitrary `json` to [SourceOptions].
+         * @param json JS object representing the [SourceOptions].
+         * @return The generated [SourceOptions].
          */
         @JvmStatic
         fun toSourceOptions(json: ReadableMap?): SourceOptions {
@@ -1190,8 +1190,15 @@ class JsonConverter {
             }
         }
 
+        /**
+         * Maps an integer value into the corresponding [BufferType] value.
+         *
+         * Currently `0` is mapped to [BufferType.ForwardDuration], and `1` to [BufferType.BackwardDuration].
+         * Other values fall back to [BufferType.ForwardDuration]
+         * @param value The integer value to seek a [BufferType] for.
+         */
         @JvmStatic
-        fun toBufferType(json: Int?): BufferType = when (json) {
+        fun toBufferType(value: Int?): BufferType = when (value) {
             0 -> BufferType.ForwardDuration
             1 -> BufferType.BackwardDuration
             else -> BufferType.ForwardDuration
diff --git a/src/bufferApi.ts b/src/bufferApi.ts
index f7b52c4c..f798eeea 100644
--- a/src/bufferApi.ts
+++ b/src/bufferApi.ts
@@ -83,8 +83,8 @@ export class BufferApi {
   }
 
   /**
-   * Returns the {@link BufferLevel} for the chosen {@link BufferType|buffer type} and {@link MediaType|media type} of the active Source.
-   * @param type The type of buffer to return the level for.
+   * Gets the {@link BufferLevel|buffer level} from the Player
+   * @param type The {@link BufferType|type of buffer} to return the level for.
    * @returns a {@link BufferLevels} that contains {@link BufferLevel} values for audio and video.
    */
   getLevel = async (type: BufferType): Promise<BufferLevels> => {