From 8cd6e0277240aff5c6f1b4e13b76d6d755d131db Mon Sep 17 00:00:00 2001
From: Joshua Sangmeister <joshua.sangmeister@gmail.com>
Date: Fri, 13 Nov 2020 16:18:34 +0100
Subject: [PATCH] Updated specs

---
 docs/interfaces/datastore-service.txt | 26 ++++++++++++++++++--------
 1 file changed, 18 insertions(+), 8 deletions(-)

diff --git a/docs/interfaces/datastore-service.txt b/docs/interfaces/datastore-service.txt
index acca052c7..be4a2cfd7 100644
--- a/docs/interfaces/datastore-service.txt
+++ b/docs/interfaces/datastore-service.txt
@@ -84,14 +84,24 @@ Interface CreateEvent {
     }
 }
 
-// Note: For deleting keys, they must be set to `None`. These keys will be removed from
-// the model.
-// list_fields can be used to partially update list fields: the values in `add` will be
-// appended to the given field, the values in `remove` will be removed from the field.
-// The case of double adding or removing something invalid will be silently ignored.
-// All given list_fields must be flat arrays of strings or ints, else an error is
-// thrown.
-// Either fields or list_fields must be given or an error will be thrown.
+/**
+ * Note: For deleting keys, they must be set to `None`. These keys will be removed from
+ * the model.
+ * list_fields can be used to partially update list fields: the values in `add` will be
+ * appended to the given field, the values in `remove` will be removed from the field.
+ * Either fields or list_fields must be given or an error will be thrown.
+ * An exception will be thrown if:
+ * - a field in list_fields is not empty and not a list
+ * - a field in list_fields contains other entries than strings or ints
+ * Other edge cases:
+ * - an element should be added that is already in the list: this element is ignored,
+ *   other potentially given elements are still added as normal
+ * - an element should be removed that is not in the list: this element is ignored,
+ *   other potentially given elements are still removed as normal
+ * - the field does not yet exist on the model:
+ *      - add: same function as if the value was given in `fields`
+ *      - remove: nothing happens
+ */
 Interface UpdateEvent {
     type: 'update';
     fqid: Fqid;