start normal filling of docs

TelegramBotAPI-extensions-utils/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/extensions/utils/updates/CallbackQueryUpdatesConversations.kt

@@ -5,12 +5,21 @@ import com.github.insanusmokrassar.TelegramBotAPI.types.update.CallbackQueryUpda
 import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.mapNotNull
 
+/**
+ * @return New [Flow] with [DataCallbackQuery] type, got from [CallbackQueryUpdate.data] field
+ */
 fun Flow<CallbackQueryUpdate>.asDataCallbackQueryFlow() = mapNotNull {
     it.data as? DataCallbackQuery
 }
+/**
+ * @return New [Flow] with [GameShortNameCallbackQuery] type, got from [CallbackQueryUpdate.data] field
+ */
 fun Flow<CallbackQueryUpdate>.asGameShortNameCallbackQueryFlow() = mapNotNull {
     it.data as? GameShortNameCallbackQuery
 }
+/**
+ * @return New [Flow] with [UnknownCallbackQueryType] type, got from [CallbackQueryUpdate.data] field
+ */
 fun Flow<CallbackQueryUpdate>.asUnknownCallbackQueryFlow() = mapNotNull {
     it.data as? UnknownCallbackQueryType
 }

TelegramBotAPI-extensions-utils/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/extensions/utils/updates/CommandsFilters.kt

@@ -8,12 +8,37 @@ import com.github.insanusmokrassar.TelegramBotAPI.types.message.content.fullEnti
 import com.github.insanusmokrassar.TelegramBotAPI.types.update.abstracts.BaseSentMessageUpdate
 import kotlinx.coroutines.flow.*
 
+/**
+ * Convert incoming [com.github.insanusmokrassar.TelegramBotAPI.types.message.abstracts.ContentMessage.content] of
+ * messages with [fullEntitiesList] and check that incoming message contains ONLY ONE [TextSource] and that is
+ * [BotCommandTextSource]. Besides, it is checking that [BotCommandTextSource.command] [Regex.matches] with incoming
+ * [commandRegex]
+ *
+ * @return The same message in case if it contains only [BotCommandTextSource] with [Regex.matches]
+ * [BotCommandTextSource.command]
+ *
+ * @see fullEntitiesList
+ * @see asContentMessagesFlow
+ * @see onlyTextContentMessages
+ */
 fun <T : BaseSentMessageUpdate> Flow<T>.filterExactCommands(
     commandRegex: Regex
 ) = asContentMessagesFlow().onlyTextContentMessages().filter { contentMessage ->
     (contentMessage.content.fullEntitiesList().singleOrNull() as? BotCommandTextSource) ?.let { commandRegex.matches(it.command) } == true
 }
 
+/**
+ * Convert incoming [com.github.insanusmokrassar.TelegramBotAPI.types.message.abstracts.ContentMessage.content] of
+ * messages with [fullEntitiesList] and check that incoming message contains [BotCommandTextSource]. Besides, it is
+ * checking that [BotCommandTextSource.command] [Regex.matches] with incoming [commandRegex]
+ *
+ * @return The same message in case if it contains somewhere in text [BotCommandTextSource] with [Regex.matches]
+ * [BotCommandTextSource.command]
+ *
+ * @see fullEntitiesList
+ * @see asContentMessagesFlow
+ * @see onlyTextContentMessages
+ */
 fun <T : BaseSentMessageUpdate> Flow<T>.filterCommandsInsideTextMessages(
     commandRegex: Regex
 ) = asContentMessagesFlow().onlyTextContentMessages().filter { contentMessage ->
@@ -23,10 +48,18 @@ fun <T : BaseSentMessageUpdate> Flow<T>.filterCommandsInsideTextMessages(
 }
 
 /**
- * @return Result [Flow] will emit all [TextSource]s to the collector ONLY IN CASE if first [TextSource] is
+ * Convert incoming [com.github.insanusmokrassar.TelegramBotAPI.types.message.abstracts.ContentMessage.content] of
- * [BotCommandTextSource] and its [BotCommandTextSource.command] is [Regex.matches] to incoming [commandRegex]. Internal
+ * messages with [fullEntitiesList] and check that incoming message contains first [TextSource] as
- * behaviour contains next rules: all incoming text sources will be passed as is, [RegularTextSource] will be divided
+ * [BotCommandTextSource]. Besides, it is checking that [BotCommandTextSource.command] [Regex.matches] with incoming
- * by " " for several [RegularTextSource] which will contains not empty args without spaces
+ * [commandRegex] and for other [TextSource] objects used next rules: all incoming text sources will be passed as is,
+ * [RegularTextSource] will be split by " " for several [RegularTextSource] which will contains not empty args without
+ * spaces.
+ *
+ * @return Converted list with first entity [BotCommandTextSource] and than all others according to rules in description
+ *
+ * @see fullEntitiesList
+ * @see asContentMessagesFlow
+ * @see onlyTextContentMessages
  */
 fun <T : BaseSentMessageUpdate> Flow<T>.filterCommandsWithArgs(
     commandRegex: Regex

TelegramBotAPI-extensions-utils/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/extensions/utils/updates/SentMessageUpdatesConversations.kt

@@ -5,14 +5,23 @@ import com.github.insanusmokrassar.TelegramBotAPI.types.update.abstracts.BaseSen
 import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.mapNotNull
 
+/**
+ * Will map incoming [BaseSentMessageUpdate]s to [ContentMessage] from [BaseSentMessageUpdate.data]
+ */
 fun <T : BaseSentMessageUpdate> Flow<T>.asContentMessagesFlow() = mapNotNull {
     it.data as? ContentMessage<*>
 }
 
+/**
+ * Will map incoming [BaseSentMessageUpdate]s to [ChatEventMessage] from [BaseSentMessageUpdate.data]
+ */
 fun <T : BaseSentMessageUpdate> Flow<T>.asChatEventsFlow() = mapNotNull {
     it.data as? ChatEventMessage
 }
 
+/**
+ * Will map incoming [BaseSentMessageUpdate]s to [UnknownMessageType] from [BaseSentMessageUpdate.data]
+ */
 fun <T : BaseSentMessageUpdate> Flow<T>.asUnknownMessagesFlow() = mapNotNull {
     it.data as? UnknownMessageType
 }

TelegramBotAPI-extensions-utils/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/extensions/utils/updates/UpdatesChatFilters.kt

@@ -7,13 +7,25 @@ import com.github.insanusmokrassar.TelegramBotAPI.types.update.abstracts.BaseMes
 import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.filter
 
+/**
+ * [Flow.filter] incoming [BaseMessageUpdate]s by their [ChatId]
+ */
 fun <T : BaseMessageUpdate> Flow<T>.filterBaseMessageUpdates(chatId: ChatId): Flow<T> = filter {
     it.data.chat.id == chatId
 }
+/**
+ * [Flow.filter] incoming [BaseMessageUpdate]s by their [ChatId] using [Chat.id] of [chat]
+ */
 fun <T : BaseMessageUpdate> Flow<T>.filterBaseMessageUpdates(chat: Chat): Flow<T> = filterBaseMessageUpdates(chat.id)
 
 
+/**
+ * [Flow.filter] incoming [SentMediaGroupUpdate]s by their [ChatId]
+ */
 fun <T : SentMediaGroupUpdate> Flow<T>.filterSentMediaGroupUpdates(chatId: ChatId): Flow<T> = filter {
     it.data.first().chat.id == chatId
 }
+/**
+ * [Flow.filter] incoming [SentMediaGroupUpdate]s by their [ChatId] using [Chat.id] of [chat]
+ */
 fun <T : SentMediaGroupUpdate> Flow<T>.filterSentMediaGroupUpdates(chat: Chat): Flow<T> = filterSentMediaGroupUpdates(chat.id)

TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/CommonAbstracts/Captioned.kt

@@ -12,7 +12,15 @@ interface CaptionedOutput : Captioned {
 }
 
 interface CaptionedInput : Captioned {
+    /**
+     * Not full list of entities. This list WILL NOT contain [TextPart]s with [com.github.insanusmokrassar.TelegramBotAPI.types.MessageEntity.textsources.RegularTextSource]
+     * @see [CaptionedInput.fullEntitiesList]
+     */
     val captionEntities: List<TextPart>
 }
 
+/**
+ * Convert its [CaptionedInput.captionEntities] to list of [com.github.insanusmokrassar.TelegramBotAPI.CommonAbstracts.TextSource]
+ * with [com.github.insanusmokrassar.TelegramBotAPI.types.MessageEntity.textsources.RegularTextSource]
+ */
 fun CaptionedInput.fullEntitiesList(): FullTextSourcesList = caption ?.fullListOfSubSource(captionEntities) ?.map { it.source } ?: emptyList()

TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/CommonAbstracts/Explained.kt

@@ -12,7 +12,15 @@ interface ExplainedOutput : Explained {
 }
 
 interface ExplainedInput : Explained {
+    /**
+     * Not full list of entities. This list WILL NOT contain [TextPart]s with [com.github.insanusmokrassar.TelegramBotAPI.types.MessageEntity.textsources.RegularTextSource]
+     * @see [ExplainedInput.fullEntitiesList]
+     */
     val explanationEntities: List<TextPart>
 }
 
+/**
+ * Convert its [ExplainedInput.explanationEntities] to list of [com.github.insanusmokrassar.TelegramBotAPI.CommonAbstracts.TextSource]
+ * with [com.github.insanusmokrassar.TelegramBotAPI.types.MessageEntity.textsources.RegularTextSource]
+ */
 fun ExplainedInput.fullEntitiesList(): FullTextSourcesList = explanation ?.fullListOfSubSource(explanationEntities) ?.map { it.source } ?: emptyList()

TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/types/message/content/TextContent.kt

@@ -14,6 +14,10 @@ import com.github.insanusmokrassar.TelegramBotAPI.utils.*
 
 data class TextContent(
     val text: String,
+    /**
+     * Not full list of entities. This list WILL NOT contain [TextPart]s with [com.github.insanusmokrassar.TelegramBotAPI.types.MessageEntity.textsources.RegularTextSource]
+     * @see [TextContent.fullEntitiesList]
+     */
     val entities: List<TextPart> = emptyList()
 ) : MessageContent {
     override fun createResend(
@@ -67,4 +71,8 @@ data class TextContent(
     }
 }
 
+/**
+ * Convert its [TextContent.entities] to list of [com.github.insanusmokrassar.TelegramBotAPI.CommonAbstracts.TextSource]
+ * with [com.github.insanusmokrassar.TelegramBotAPI.types.MessageEntity.textsources.RegularTextSource]
+ */
 fun TextContent.fullEntitiesList(): FullTextSourcesList = text.fullListOfSubSource(entities).map { it.source }