behaviours documentatio and changing of buildBehaviour signature

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## 0.31.0
 
+* `Behaviour Builder`:
+    * Extension `TelegramBot#buildBehaviour` have changed its return value: now it is `Job` instead of
+      `FlowsUpdatesFilter`
+
 ## 0.30.13
 
 * `Common`:

tgbotapi.core/src/commonMain/kotlin/dev/inmo/tgbotapi/types/InlineQueries/InlineQueryResult/abstracts/results/audio/InlineQueryResultAudioCommon.kt

@@ -8,10 +8,5 @@ import dev.inmo.tgbotapi.types.InlineQueries.InlineQueryResult.abstracts.WithInp
 const val inlineQueryResultAudioType = "audio"
 
 interface InlineQueryResultAudioCommon : InlineQueryResult,
-    CaptionedOutput,
     TextedOutput,
-    WithInputMessageContentInlineQueryResult {
-    @Deprecated("Will be removed in next major release")
-    override val caption: String?
-        get() = text
-}
+    WithInputMessageContentInlineQueryResult

tgbotapi.extensions.behaviour_builder/src/commonMain/kotlin/dev/inmo/tgbotapi/extensions/behaviour_builder/BehaviourBuilders.kt

@@ -3,8 +3,19 @@ package dev.inmo.tgbotapi.extensions.behaviour_builder
 import dev.inmo.tgbotapi.bot.TelegramBot
 import dev.inmo.tgbotapi.extensions.utils.updates.retrieving.startGettingOfUpdatesByLongPolling
 import dev.inmo.tgbotapi.updateshandlers.FlowsUpdatesFilter
+import dev.inmo.tgbotapi.utils.PreviewFeature
 import kotlinx.coroutines.CoroutineScope
 
+/**
+ * Use this method in case you wish to make some additional actions with [flowUpdatesFilter].
+ *
+ * **WARNING** This method WILL NOT launch any listening of updates. Use something like
+ * [startGettingOfUpdatesByLongPolling] or tools for work with webhooks
+ *
+ * @see [BehaviourContext]
+ * @see startGettingOfUpdatesByLongPolling
+ */
+@PreviewFeature
 suspend fun TelegramBot.buildBehaviour(
     scope: CoroutineScope,
     flowUpdatesFilter: FlowsUpdatesFilter,
@@ -17,10 +28,19 @@ suspend fun TelegramBot.buildBehaviour(
     ).block()
 }
 
+/**
+ * Use this method to build bot behaviour and run it via long polling. In case you wish to get [FlowsUpdatesFilter] for
+ * additional manipulations, you must provide external [FlowsUpdatesFilter] in other [buildBehaviour] function.
+ *
+ * @see buildBehaviour
+ * @see BehaviourContext
+ * @see startGettingOfUpdatesByLongPolling
+ */
+@PreviewFeature
 suspend fun TelegramBot.buildBehaviour(
     scope: CoroutineScope,
     block: BehaviourContextReceiver<Unit>
-) = FlowsUpdatesFilter().also {
+) = FlowsUpdatesFilter().let {
     buildBehaviour(
         scope,
         it,

tgbotapi.extensions.behaviour_builder/src/commonMain/kotlin/dev/inmo/tgbotapi/extensions/behaviour_builder/BehaviourContext.kt

@@ -8,6 +8,13 @@ import kotlinx.coroutines.CoroutineScope
 typealias BehaviourContextReceiver<T> = suspend BehaviourContext.() -> T
 typealias BehaviourContextAndTypeReceiver<T, I> = suspend BehaviourContext.(I) -> T
 
+/**
+ * This class contains all necessary tools for work with bots and especially for [buildBehaviour]
+ *
+ * @param scope This param will be used for creating of some subscriptions inside of methods, updates listening and
+ * different other things in context of working with [CoroutineScope] and coroutines.
+ * @param flowsUpdatesFilter This parameter will be used to subscribe on different types of update
+ */
 data class BehaviourContext(
     val bot: TelegramBot,
     val scope: CoroutineScope,