fixes in media groups collecting and kdocs

tgbotapi.utils/src/commonMain/kotlin/dev/inmo/tgbotapi/extensions/utils/updates/UpdatesUtils.kt

@@ -27,7 +27,8 @@ fun List<Update>.lastUpdateIdentifier(): UpdateIdentifier? {
 }
 
 /**
- * Will convert incoming list of updates to list with [MediaGroupUpdate]s
+ * Will convert incoming list of [Update]s to list with [Update]s, which include [dev.inmo.tgbotapi.types.message.abstracts.ContentMessage]s
+ * with [dev.inmo.tgbotapi.types.message.content.MediaGroupContent]
  */
 fun List<Update>.convertWithMediaGroupUpdates(): List<Update> {
     val resultUpdates = mutableListOf<Update>()
@@ -67,4 +68,5 @@ fun List<Update>.convertWithMediaGroupUpdates(): List<Update> {
  *
  * @throws IllegalStateException
  */
+@Deprecated("Redundant", ReplaceWith("this"))
 fun BaseEditMessageUpdate.toEditMediaGroupUpdate() = this

tgbotapi.utils/src/commonMain/kotlin/dev/inmo/tgbotapi/extensions/utils/updates/retrieving/LongPolling.kt

@@ -21,7 +21,8 @@ import kotlinx.coroutines.flow.*
 
 /**
  * @param mediaGroupsDebounceTimeMillis Will be used for calling of [updateHandlerWithMediaGroupsAdaptation]. Pass null
- * in case you wish to enable classic way of updates handling
+ * in case you wish to enable classic way of updates handling, but in that mode some media group messages can be
+ * retrieved in different updates
  */
 fun TelegramBot.longPollingFlow(
     timeoutSeconds: Seconds = 30,
@@ -129,6 +130,11 @@ fun TelegramBot.longPollingFlow(
     }
 }
 
+/**
+ * @param mediaGroupsDebounceTimeMillis Will be used for calling of [updateHandlerWithMediaGroupsAdaptation]. Pass null
+ * in case you wish to enable classic way of updates handling, but in that mode some media group messages can be
+ * retrieved in different updates
+ */
 fun TelegramBot.startGettingOfUpdatesByLongPolling(
     timeoutSeconds: Seconds = 30,
     scope: CoroutineScope = CoroutineScope(Dispatchers.Default),
@@ -152,6 +158,10 @@ fun TelegramBot.startGettingOfUpdatesByLongPolling(
 )
 
 /**
+ * @param mediaGroupsDebounceTimeMillis Will be used for calling of [updateHandlerWithMediaGroupsAdaptation]. Pass null
+ * in case you wish to enable classic way of updates handling, but in that mode some media group messages can be
+ * retrieved in different updates
+ *
  * @return [kotlinx.coroutines.flow.Flow] which will emit updates to the collector while they will be accumulated. Works
  * the same as [longPollingFlow], but it will cancel the flow after the first one [HttpRequestTimeoutException]
  */
@@ -179,6 +189,11 @@ fun TelegramBot.createAccumulatedUpdatesRetrieverFlow(
     !(it is InlineQueryUpdate && avoidInlineQueries || it is CallbackQueryUpdate && avoidCallbackQueries)
 }
 
+/**
+ * @param mediaGroupsDebounceTimeMillis Will be used for calling of [updateHandlerWithMediaGroupsAdaptation]. Pass null
+ * in case you wish to enable classic way of updates handling, but in that mode some media group messages can be
+ * retrieved in different updates
+ */
 fun TelegramBot.retrieveAccumulatedUpdates(
     avoidInlineQueries: Boolean = false,
     avoidCallbackQueries: Boolean = false,
@@ -201,6 +216,11 @@ fun TelegramBot.retrieveAccumulatedUpdates(
     updatesReceiver(it)
 }
 
+/**
+ * @param mediaGroupsDebounceTimeMillis Will be used for calling of [updateHandlerWithMediaGroupsAdaptation]. Pass null
+ * in case you wish to enable classic way of updates handling, but in that mode some media group messages can be
+ * retrieved in different updates
+ */
 fun TelegramBot.retrieveAccumulatedUpdates(
     flowsUpdatesFilter: FlowsUpdatesFilter,
     avoidInlineQueries: Boolean = false,
@@ -220,6 +240,11 @@ fun TelegramBot.retrieveAccumulatedUpdates(
     flowsUpdatesFilter.asUpdateReceiver
 )
 
+/**
+ * @param mediaGroupsDebounceTimeMillis Will be used for calling of [updateHandlerWithMediaGroupsAdaptation]. Pass null
+ * in case you wish to enable classic way of updates handling, but in that mode some media group messages can be
+ * retrieved in different updates
+ */
 suspend fun TelegramBot.flushAccumulatedUpdates(
     avoidInlineQueries: Boolean = false,
     avoidCallbackQueries: Boolean = false,
@@ -241,8 +266,12 @@ suspend fun TelegramBot.flushAccumulatedUpdates(
 ).join()
 
 /**
- * Will [startGettingOfUpdatesByLongPolling] using incoming [flowsUpdatesFilter]. It is assumed that you ALREADY CONFIGURE
+ * Will [startGettingOfUpdatesByLongPolling] using incoming [updatesFilter]. It is assumed that you ALREADY CONFIGURE
  * all updates receivers, because this method will trigger getting of updates and.
+ *
+ * @param mediaGroupsDebounceTimeMillis Will be used for calling of [updateHandlerWithMediaGroupsAdaptation]. Pass null
+ * in case you wish to enable classic way of updates handling, but in that mode some media group messages can be
+ * retrieved in different updates
  */
 fun TelegramBot.longPolling(
     updatesFilter: UpdatesFilter,
@@ -269,6 +298,10 @@ fun TelegramBot.longPolling(
  * Will enable [longPolling] by creating [FlowsUpdatesFilter] with [flowsUpdatesFilterUpdatesKeeperCount] as an argument
  * and applied [flowUpdatesPreset]. It is assumed that you WILL CONFIGURE all updates receivers in [flowUpdatesPreset],
  * because of after [flowUpdatesPreset] method calling will be triggered getting of updates.
+ *
+ * @param mediaGroupsDebounceTimeMillis Will be used for calling of [updateHandlerWithMediaGroupsAdaptation]. Pass null
+ * in case you wish to enable classic way of updates handling, but in that mode some media group messages can be
+ * retrieved in different updates
  */
 @Suppress("unused")
 fun TelegramBot.longPolling(
@@ -282,6 +315,11 @@ fun TelegramBot.longPolling(
     flowUpdatesPreset: FlowsUpdatesFilter.() -> Unit
 ): Job = longPolling(FlowsUpdatesFilter(flowsUpdatesFilterUpdatesKeeperCount).apply(flowUpdatesPreset), timeoutSeconds, scope, autoDisableWebhooks, autoSkipTimeoutExceptions, mediaGroupsDebounceTimeMillis, exceptionsHandler)
 
+/**
+ * @param mediaGroupsDebounceTimeMillis Will be used for calling of [updateHandlerWithMediaGroupsAdaptation]. Pass null
+ * in case you wish to enable classic way of updates handling, but in that mode some media group messages can be
+ * retrieved in different updates
+ */
 fun RequestsExecutor.startGettingOfUpdatesByLongPolling(
     updatesFilter: UpdatesFilter,
     timeoutSeconds: Seconds = 30,

tgbotapi.utils/src/commonMain/kotlin/dev/inmo/tgbotapi/extensions/utils/updates/retrieving/MediaGroupsIncluder.kt

@@ -1,6 +1,5 @@
 package dev.inmo.tgbotapi.extensions.utils.updates.retrieving
 
-import dev.inmo.micro_utils.coroutines.launchSafely
 import dev.inmo.micro_utils.coroutines.launchSafelyWithoutExceptions
 import dev.inmo.tgbotapi.extensions.utils.updates.convertWithMediaGroupUpdates
 import dev.inmo.tgbotapi.types.message.abstracts.PossiblyMediaGroupMessage
@@ -12,7 +11,6 @@ import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.channels.Channel
 import kotlinx.coroutines.launch
 
-
 /**
  * Create [UpdateReceiver] object which will correctly accumulate updates and send into output updates which INCLUDE
  * [dev.inmo.tgbotapi.types.update.MediaGroupUpdates.MediaGroupUpdate]s.

tgbotapi.utils/src/jvmMain/kotlin/dev/inmo/tgbotapi/extensions/utils/updates/retrieving/Webhook.kt

@@ -26,6 +26,9 @@ import java.util.concurrent.Executors
  * @param [scope] Will be used for mapping of media groups
  * @param [exceptionsHandler] Pass this parameter to set custom exception handler for getting updates
  * @param [block] Some receiver block like [dev.inmo.tgbotapi.updateshandlers.FlowsUpdatesFilter]
+ * @param mediaGroupsDebounceTimeMillis Will be used for calling of [updateHandlerWithMediaGroupsAdaptation]. Pass null
+ * in case you wish to enable classic way of updates handling, but in that mode some media group messages can be
+ * retrieved in different updates
  *
  * @see dev.inmo.tgbotapi.updateshandlers.FlowsUpdatesFilter
  * @see UpdatesFilter
@@ -57,6 +60,11 @@ fun Route.includeWebhookHandlingInRoute(
     }
 }
 
+/**
+ * @param mediaGroupsDebounceTimeMillis Will be used for calling of [updateHandlerWithMediaGroupsAdaptation]. Pass null
+ * in case you wish to enable classic way of updates handling, but in that mode some media group messages can be
+ * retrieved in different updates
+ */
 fun Route.includeWebhookHandlingInRouteWithFlows(
     scope: CoroutineScope,
     exceptionsHandler: ExceptionHandler<Unit>? = null,
@@ -76,6 +84,9 @@ fun Route.includeWebhookHandlingInRouteWithFlows(
  * @param listenRoute address to listen by bot. If null - will be set up in root of host
  * @param scope Scope which will be used for
  * @param privateKeyConfig If configured - server will be created with [sslConnector]. [connector] will be used otherwise
+ * @param mediaGroupsDebounceTimeMillis Will be used for calling of [updateHandlerWithMediaGroupsAdaptation]. Pass null
+ * in case you wish to enable classic way of updates handling, but in that mode some media group messages can be
+ * retrieved in different updates
  *
  * @see dev.inmo.tgbotapi.updateshandlers.FlowsUpdatesFilter
  * @see UpdatesFilter
@@ -132,6 +143,9 @@ fun startListenWebhooks(
  * @param listenPort port which will be listen by bot
  * @param listenRoute address to listen by bot
  * @param scope Scope which will be used for
+ * @param mediaGroupsDebounceTimeMillis Will be used for calling of [updateHandlerWithMediaGroupsAdaptation]. Pass null
+ * in case you wish to enable classic way of updates handling, but in that mode some media group messages can be
+ * retrieved in different updates
  *
  * @see dev.inmo.tgbotapi.updateshandlers.FlowsUpdatesFilter
  * @see UpdatesFilter