Add api docs for mutable message fields #44
Conversation
Which were not very good
|
|
||
| | Enum | Spec | Description | | ||
| |---|---|---| | ||
| | MESSAGE_UNSET | TM5 | (The field is unset, eg a `Message` retrieved from before the `action` field was added) | |
There was a problem hiding this comment.
In this case, I thought RT would set these to message.create when sending over the wire considering all messages before action was introduced are by definition a message.create? Or is that not the case?
There was a problem hiding this comment.
I'm thinking here about history, realtime messages aren't an issue.
We could certainly say that every message with no action is implicitly a CREATE (and have the history api do that), but then the obvious question is, if that's the semantics we want then why do we even have an UNSET, why not make CREATE zero? @lmars you defined the enum, wdyt?
| |---|---|---| | ||
| | MESSAGE_UNSET | TM5 | (The field is unset, eg a `Message` retrieved from before the `action` field was added) | | ||
| | MESSAGE_CREATE | TM5 | A normal message that has been published by a user. | | ||
| | MESSAGE_UPDATE | TM5 | An update that edits a previously-published message (referenced by `serial`). | |
There was a problem hiding this comment.
Small nit pick, but could we say something like..
| | MESSAGE_UPDATE | TM5 | An update that edits a previously-published message (referenced by `serial`). | | |
| | MESSAGE_UPDATE | TM5 | An update that modifies a previously-published message (referenced by `serial`). | |
Just so we are consistent with the wording of 'update` everywhere?
| | MESSAGE_UPDATE | TM5 | An update that edits a previously-published message (referenced by `serial`). | | ||
| | MESSAGE_DELETE | TM5 | A deletion of a previously-published message (referenced by `serial`). | | ||
| | ANNOTATION_CREATE | TM5 | An annotation added to a previously-published message (referenced by serial). | | ||
| | ANNOTATION_DELETE | TM5 | A deletion of a previously-published annotation. | |
There was a problem hiding this comment.
If we are talking about adding annotations above, can we reword the below to say something like
| | ANNOTATION_DELETE | TM5 | A deletion of a previously-published annotation. | | |
| | ANNOTATION_DELETE | TM5 | A deletion of a annotation that was previously added to a published message. | |
There was a problem hiding this comment.
the help text for ANNOTATION_DELETE is pretty much a placeholder since I don't think we've even started discussing how deleting annotations would work. (or has the chat team discussed this?)
| @@ -635,7 +649,23 @@ Contains an individual message that is sent to, or received from, Ably. | |||
| | extras: JsonObject? ||| TM2i | A JSON object of arbitrary key-value pairs that may contain metadata, and/or ancillary payloads. Valid payloads include [`push`]{@link Push}, [`delta`]{@link DeltaExtras}, [`ref`]{@link ReferenceExtras} and `headers`. | | |||
| | id: String ||| TM2a | A Unique ID assigned by Ably to this message. | | |||
| | name: String? ||| TM2g | The event name. | | |||
| | timestamp: Time ||| TM2f | Timestamp of when the message was received by Ably, as milliseconds since the Unix epoch. | | |||
| | timestamp: Time ||| TM2f | Timestamp of when the message was received by Ably, as milliseconds since the Unix epoch. (This is the timestamp of the current version of the message) | | |||
| | serial: String? ||| TM2k | This message's unique serial (an identifier that — unlike the id — will remain the same in all future updates of this message, and can be used to update or delete that message). | | |||
There was a problem hiding this comment.
Serial is also lexicographically sortable, can we mention this here too?
| | timestamp: Time ||| TM2f | Timestamp of when the message was received by Ably, as milliseconds since the Unix epoch. (This is the timestamp of the current version of the message) | | ||
| | serial: String? ||| TM2k | This message's unique serial (an identifier that — unlike the id — will remain the same in all future updates of this message, and can be used to update or delete that message). | | ||
| | version: String? ||| TM2p | The version of the message, lexicographically-comparable with other versions (that share the same serial) Will differ from the serial only if the message has been updated or deleted. | | ||
| | refSerial: String? ||| TM2l | If this message references another, the serial of that message. | |
There was a problem hiding this comment.
| | refSerial: String? ||| TM2l | If this message references another, the serial of that message. | | |
| | refSerial: String? ||| TM2l | If this message references another, the serial of that referenced message. | |
| | Method / Property | Parameter | Returns | Spec | Description | | ||
| |---|---|---|---|---| | ||
| | clientId: string ||| TM2n1 | ClientId of the user who triggered the update or delete. | | ||
| | description: string ||| TM2n2 | Reason for the update or delete provided by of the user who triggered it. | |
There was a problem hiding this comment.
Each of these (bar the clientId perhaps) should be optional
...And update the descriptions of presence actions, which were not great