From b93ce07bb3fe285930d6b72c35f6e38475e6af06 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edwin=20T=C3=B6r=C3=B6k?= Date: Thu, 21 Nov 2024 18:15:00 +0000 Subject: [PATCH] CP-52707: Improve Event.from/next API documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Describe EVENTS_LOST in Event.next. Remove EVENTS_LOST and SESSION_NOT_REGISTERED from Event.from: these are only raised by Event.next. Document the actual errors that Event.from can raise. Signed-off-by: Edwin Török --- ocaml/idl/datamodel.ml | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/ocaml/idl/datamodel.ml b/ocaml/idl/datamodel.ml index 83d5d1740c3..40974fbcc9d 100644 --- a/ocaml/idl/datamodel.ml +++ b/ocaml/idl/datamodel.ml @@ -8517,11 +8517,18 @@ module Event = struct ] ~doc: "Blocking call which returns a (possibly empty) batch of events. This \ - method is only recommended for legacy use. New development should use \ - event.from which supersedes this method." + method is only recommended for legacy use.It stores events in a \ + buffer of limited size, raising EVENTS_LOST if too many events got \ + generated. New development should use event.from which supersedes \ + this method." ~custom_marshaller:true ~flags:[`Session] ~result:(Set (Record _event), "A set of events") - ~errs:[Api_errors.session_not_registered; Api_errors.events_lost] + ~errs: + [ + Api_errors.session_not_registered + ; Api_errors.events_lost + ; Api_errors.event_subscription_parse_failure + ] ~allowed_roles:_R_ALL () let from = @@ -8551,7 +8558,8 @@ module Event = struct ~doc: "Blocking call which returns a new token and a (possibly empty) batch \ of events. The returned token can be used in subsequent calls to this \ - function." + function. It eliminates redundant events (e.g. same field updated \ + multiple times)." ~custom_marshaller:true ~flags:[`Session] ~result: ( Set (Record _event) @@ -8562,7 +8570,11 @@ module Event = struct (*In reality the event batch is not a set of records as stated here. Due to the difficulty of representing this in the datamodel, the doc is generated manually, so ensure the markdown_backend.ml and gen_json.ml is updated if something changes. *) - ~errs:[Api_errors.session_not_registered; Api_errors.events_lost] + ~errs: + [ + Api_errors.event_from_token_parse_failure + ; Api_errors.event_subscription_parse_failure + ] ~allowed_roles:_R_ALL () let get_current_id =