From f80f3f3308984cc0999cb539360a7b9b2d2905b4 Mon Sep 17 00:00:00 2001
From: Janne Mareike Koschinski <janne@kuschku.de>
Date: Tue, 1 Mar 2022 19:26:59 +0100
Subject: [PATCH] feat: improve docs for backlog loading
---
docs/protocol/signalproxy/objects.md | 86 ++++++++++++++++++----------
1 file changed, 56 insertions(+), 30 deletions(-)
diff --git a/docs/protocol/signalproxy/objects.md b/docs/protocol/signalproxy/objects.md
index bcd8c6f..ffd1f92 100644
--- a/docs/protocol/signalproxy/objects.md
+++ b/docs/protocol/signalproxy/objects.md
@@ -125,35 +125,56 @@ interface BacklogManager {
// C->S calls
/**
- * Loads backlog for `bufferId`, starting at message `first`, up to `last`
- * (plus `additional` more messages after `last`) but at most `limit`
- * messages total.
- *
- * first == -1 && last == -1: highest $limit messages
- * last == -1: $msgid in [$first, ∞), highest $limit
- * else: $msgid in [$first, $last), highest $limit messages
+ * Loads backlog for [bufferId], where the message id is >= [first] and < [last].
+ * If [first] or [last] is unset, the list will be unbounded in that direction.
+ *
+ * If a [limit] is set, the list will be truncated to the newest N messages.
+ *
+ * If both [first] and [last] are set, and the list of messages is not truncated by [limit],
+ * [additional] messages will be loaded before [last].
*/
requestBacklog(bufferId: BufferId, first: MsgId, last: MsgId, limit: Int, additional: Int)
/**
- * Same as `requestBacklog`, but only messages of a certain message `type`
- * with certain `flags` set.
+ * Loads backlog for [bufferId], where the message id is >= [first] and < [last].
+ * If [first] or [last] is unset, the list will be unbounded in that direction.
+ *
+ * If a [limit] is set, the list will be truncated to the newest N messages.
+ *
+ * If both [first] and [last] are set, and the list of messages is not truncated by [limit],
+ * [additional] messages will be loaded before [last].
+ *
+ * Only messages matching [type] and [flags] will be returned and counted.
*/
requestBacklogFiltered(bufferId: BufferId, first: MsgId, last: MsgId, limit: Int, additional: Int, type: Int, flags: Int)
/**
- * Same as `requestBacklog`, but only messages of a certain message `type`
- * with certain `flags` set.
+ * Loads backlog for [bufferId], where the message id is >= [first] and < [last].
+ * If [first] or [last] is unset, the list will be unbounded in that direction.
+ *
+ * If a [limit] is set, the list will be truncated to the oldest N messages.
*
- * first == -1 && last == -1: lowest $limit messages
- * last == -1: $msgid in [$first, ∞), lowest $limit
- * else: $msgid in [$first, $last), lowest $limit messages
+ * Only messages matching [type] and [flags] will be returned and counted.
*/
requestBacklogForward(bufferId: BufferId, first: MsgId, last: MsgId, limit: Int, type: Int, flags: Int)
/**
- * Same as `requestBacklog`, but applied to all buffers.
+ * Loads backlog for all buffers, where the message id is >= [first] and < [last].
+ * If [first] or [last] is unset, the list will be unbounded in that direction.
+ *
+ * If a [limit] is set, the list will be truncated to the newest N messages.
+ *
+ * If both [first] and [last] are set, and the list of messages is not truncated by [limit],
+ * [additional] messages will be loaded before [last].
*/
requestBacklogAll(first: MsgId, last: MsgId, limit: Int, additional: Int)
/**
- * Same as `requestBacklogFiltered`, but applied to all buffers.
+ * Loads backlog for all buffers, where the message id is >= [first] and < [last].
+ * If [first] or [last] is unset, the list will be unbounded in that direction.
+ *
+ * If a [limit] is set, the list will be truncated to the newest N messages.
+ *
+ * If both [first] and [last] are set, and the list of messages is not truncated by [limit],
+ * [additional] messages will be loaded before [last].
+ *
+ * Only messages matching [type] and [flags] will be returned and counted.
*/
requestBacklogAllFiltered(first: MsgId, last: MsgId, limit: Int, additional: Int, type: Int, flags: Int)
@@ -161,23 +182,28 @@ interface BacklogManager {
// S->C calls
/**
- * The response to `requestBacklog`, with the messages encoded as QVariants
- * in the `messages` parameter.
+ * Response to the corresponding [requestBacklog] call.
+ * [messages] contains the messages as `QVariant<Message>`
*/
receiveBacklog(bufferId: BufferId, first: MsgId, last: MsgId, limit: Int, additional: Int, messages: QVariantList)
/**
- * The response to `requestBacklogFiltered`, with the messages encoded as
- * QVariants in the `messages` parameter.
+ * Response to the corresponding [requestBacklogFiltered] call.
+ * [messages] contains the messages as `QVariant<Message>`
*/
receiveBacklogFiltered(bufferId: BufferId, first: MsgId, last: MsgId, limit: Int, additional: Int, type: Int, flags: Int, messages: QVariantList)
/**
- * The response to `requestBacklogAll`, with the messages encoded as
- * QVariants in the `messages` parameter.
+ * Response to the corresponding [requestBacklogForward] call.
+ * [messages] contains the messages as `QVariant<Message>`
+ */
+ receiveBacklogForward(bufferId: BufferId, first: MsgId, last: MsgId, limit: Int, type: Int, flags: Int, messages: QVariantList)
+ /**
+ * Response to the corresponding [requestBacklogAll] call.
+ * [messages] contains the messages as `QVariant<Message>`
*/
receiveBacklogAll(first: MsgId, last: MsgId, limit: Int, additional: Int, messages: QVariantList)
/**
- * The response to `requestBacklogAllFiltered`, with the messages encoded as
- * QVariants in the `messages` parameter.
+ * Response to the corresponding [requestBacklogAllFiltered] call.
+ * [messages] contains the messages as `QVariant<Message>`
*/
receiveBacklogAllFiltered(first: MsgId, last: MsgId, limit: Int, additional: Int, type: Int, flags: Int, messages: QVariantList)
}
@@ -185,8 +211,8 @@ interface BacklogManager {
**Network**
-Its network representation is an empty `QVariantMap`, as it has no syncable fields. For the same reason it also does **
-not** support the otherwise standard `update` call.
+Its network representation is an empty `QVariantMap`, as it has no syncable fields. For the same reason it also does
+**not** support the otherwise standard `update` call.
## BufferSyncer
@@ -900,15 +926,15 @@ interface IrcListHelper {
**Network**
-Its network representation is an empty `QVariantMap`, as it has no syncable fields. For the same reason it also does **
-not** support the otherwise standard `update` call.
+Its network representation is an empty `QVariantMap`, as it has no syncable fields. For the same reason it also does
+**not** support the otherwise standard `update` call.
## IrcUser
**ObjectName**
-The objectName of an IrcUser is the string representation of the networkId of the network it belongs to, followed by a "
-/", followed by the nick of the user.
+The objectName of an IrcUser is the string representation of the networkId of the network it belongs to, followed by a
+"/", followed by the nick of the user.
Example: `4/justJanne`
--
GitLab