From 6a41bd9b82c990d1dd668bd77b97e53ac5577c2a Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Thu, 21 May 2015 12:02:07 +0100 Subject: [PATCH] Add descriptions to event fields --- event-schemas/schema/v1/m.presence | 13 +++++--- event-schemas/schema/v1/m.room.aliases | 1 + event-schemas/schema/v1/m.room.create | 3 +- event-schemas/schema/v1/m.room.join_rules | 1 + event-schemas/schema/v1/m.room.member | 7 ++-- event-schemas/schema/v1/m.room.message | 8 +++-- .../schema/v1/m.room.message.feedback | 8 +++-- event-schemas/schema/v1/m.room.name | 5 +-- event-schemas/schema/v1/m.room.power_levels | 32 +++++++++++++++---- event-schemas/schema/v1/m.room.redaction | 8 +++-- event-schemas/schema/v1/m.room.topic | 5 +-- 11 files changed, 65 insertions(+), 26 deletions(-) diff --git a/event-schemas/schema/v1/m.presence b/event-schemas/schema/v1/m.presence index 815c6af9..f7cc6048 100644 --- a/event-schemas/schema/v1/m.presence +++ b/event-schemas/schema/v1/m.presence @@ -6,20 +6,25 @@ "type": "object", "properties": { "avatar_url": { - "type": "string" + "type": "string", + "description": "The current avatar URL for this user, if any." }, "displayname": { - "type": "string" + "type": "string", + "description": "The current display name for this user, if any." }, "last_active_ago": { - "type": "number" + "type": "number", + "description": "The last time since this used performed some action, in milliseconds." }, "presence": { "type": "string", + "description": "The presence state for this user.", "enum": ["online", "offline", "unavailable", "free_for_chat", "hidden"] }, "user_id": { - "type": "string" + "type": "string", + "description": "The user's ID." } }, "required": ["presence", "user_id"] diff --git a/event-schemas/schema/v1/m.room.aliases b/event-schemas/schema/v1/m.room.aliases index 03842221..6bfa50f8 100644 --- a/event-schemas/schema/v1/m.room.aliases +++ b/event-schemas/schema/v1/m.room.aliases @@ -12,6 +12,7 @@ "properties": { "aliases": { "type": "array", + "description": "A list of room aliases.", "items": { "type": "string" } diff --git a/event-schemas/schema/v1/m.room.create b/event-schemas/schema/v1/m.room.create index 53bb1a45..f133124a 100644 --- a/event-schemas/schema/v1/m.room.create +++ b/event-schemas/schema/v1/m.room.create @@ -11,7 +11,8 @@ "type": "object", "properties": { "creator": { - "type": "string" + "type": "string", + "description": "The ``user_id`` of the room creator. This is set by the homeserver." } }, "required": ["creator"] diff --git a/event-schemas/schema/v1/m.room.join_rules b/event-schemas/schema/v1/m.room.join_rules index 7c8189b2..16f5c9a6 100644 --- a/event-schemas/schema/v1/m.room.join_rules +++ b/event-schemas/schema/v1/m.room.join_rules @@ -12,6 +12,7 @@ "properties": { "join_rule": { "type": "string", + "description": "The type of rules used for users wishing to join this room.", "enum": ["public","knock","invite","private"] } }, diff --git a/event-schemas/schema/v1/m.room.member b/event-schemas/schema/v1/m.room.member index 5cd8d297..a14a6c91 100644 --- a/event-schemas/schema/v1/m.room.member +++ b/event-schemas/schema/v1/m.room.member @@ -12,13 +12,16 @@ "properties": { "membership": { "type": "string", + "description": "The membership state of the user.", "enum": ["invite","join","knock","leave","ban"] }, "avatar_url": { - "type": "string" + "type": "string", + "description": "The avatar URL for this user, if any. This is added by the homeserver." }, "displayname": { - "type": "string" + "type": "string", + "description": "The display name for this user, if any. This is added by the homeserver." } }, "required": ["membership"] diff --git a/event-schemas/schema/v1/m.room.message b/event-schemas/schema/v1/m.room.message index e5a109f7..a849f07f 100644 --- a/event-schemas/schema/v1/m.room.message +++ b/event-schemas/schema/v1/m.room.message @@ -1,7 +1,7 @@ { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", - "title": "A human-readable message in the room.", + "title": "Message", "description": "This event is used when sending messages in a room. Messages are not limited to be text. The ``msgtype`` key outlines the type of message, e.g. text, audio, image, video, etc. The ``body`` key is text and MUST be used with every kind of ``msgtype`` as a fallback mechanism for when a client cannot render a message.", "allOf": [{ "$ref": "core#/definitions/room_event" @@ -11,10 +11,12 @@ "type": "object", "properties": { "msgtype": { - "type": "string" + "type": "string", + "description": "The type of message, e.g. ``m.image``, ``m.text``" }, "body": { - "type": "string" + "type": "string", + "description": "The textual representation of this message." } }, "required": ["msgtype", "body"] diff --git a/event-schemas/schema/v1/m.room.message.feedback b/event-schemas/schema/v1/m.room.message.feedback index 62c75e32..4cfd44d1 100644 --- a/event-schemas/schema/v1/m.room.message.feedback +++ b/event-schemas/schema/v1/m.room.message.feedback @@ -1,8 +1,8 @@ { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", - "title": "A receipt for a message. N.B. not implemented in Synapse, and superceded in v2 CS API by the ``relates_to`` event field.", - "description": "Feedback events are events sent to acknowledge a message in some way. There are two supported acknowledgements: ``delivered`` (sent when the event has been received) and ``read`` (sent when the event has been observed by the end-user). The ``target_event_id`` should reference the ``m.room.message`` event being acknowledged.", + "title": "MessageFeedback", + "description": "Feedback events are events sent to acknowledge a message in some way. There are two supported acknowledgements: ``delivered`` (sent when the event has been received) and ``read`` (sent when the event has been observed by the end-user). The ``target_event_id`` should reference the ``m.room.message`` event being acknowledged. N.B. not implemented in Synapse, and superceded in v2 CS API by the ``relates_to`` event field.", "allOf": [{ "$ref": "core#/definitions/room_event" }], @@ -12,10 +12,12 @@ "properties": { "type": { "type": "string", + "description": "The type of feedback.", "enum": ["delivered", "read"] }, "target_event_id": { - "type": "string" + "type": "string", + "description": "The event that this feedback is related to." } }, "required": ["type", "target_event_id"] diff --git a/event-schemas/schema/v1/m.room.name b/event-schemas/schema/v1/m.room.name index 3d70fa16..ba990c61 100644 --- a/event-schemas/schema/v1/m.room.name +++ b/event-schemas/schema/v1/m.room.name @@ -1,6 +1,6 @@ { "$schema": "http://json-schema.org/draft-04/schema#", - "title": "Set the human-readable name for the room.", + "title": "RoomName", "description": "A room has an opaque room ID which is not human-friendly to read. A room alias is human-friendly, but not all rooms have room aliases. The room name is a human-friendly string designed to be displayed to the end-user. The room name is not unique, as multiple rooms can have the same room name set. The room name can also be set when creating a room using ``/createRoom`` with the ``name`` key.", "type": "object", "allOf": [{ @@ -11,7 +11,8 @@ "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "The name of the room." } }, "required": ["name"] diff --git a/event-schemas/schema/v1/m.room.power_levels b/event-schemas/schema/v1/m.room.power_levels index 6e425025..d439e4a0 100644 --- a/event-schemas/schema/v1/m.room.power_levels +++ b/event-schemas/schema/v1/m.room.power_levels @@ -10,15 +10,34 @@ "content": { "type": "object", "properties": { - "ban": { "type": "number" }, - "events_default": { "type": "number" }, - "kick": { "type": "number" }, - "redact": { "type": "number" }, - "state_default": { "type": "number" }, - "users_default": { "type": "number" }, + "ban": { + "type": "number", + "description": "The level required to ban a user." + }, + "events_default": { + "type": "number", + "description": "The default level required to send message events. Can be overidden by the ``events`` key." + }, + "kick": { + "type": "number", + "description": "The level required to kick a user." + }, + "redact": { + "type": "number", + "description": "The level required to redact an event." + }, + "state_default": { + "type": "number", + "description": "The default level required to send state events. Can be overriden by the ``events`` key." + }, + "users_default": { + "type": "number", + "description": "The default power level for every user in the room, unless their ``user_id`` is mentioned in the ``users`` key." + }, "events": { "type": "object", "title": "Event power levels", + "description": "The level required to send specific event types. This is a mapping from event type to power level required.", "additionalProperties": { "type": "number" } @@ -26,6 +45,7 @@ "users": { "type": "object", "title": "User power levels", + "description": "The power levels for specific users. This is a mapping from ``user_id`` to power level for that user.", "additionalProperties": { "type": "number" } diff --git a/event-schemas/schema/v1/m.room.redaction b/event-schemas/schema/v1/m.room.redaction index fb6dd997..2896c0da 100644 --- a/event-schemas/schema/v1/m.room.redaction +++ b/event-schemas/schema/v1/m.room.redaction @@ -1,7 +1,7 @@ { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", - "title": "Indicates a previous event has been redacted.", + "title": "Redaction", "description": "Events can be redacted by either room or server admins. Redacting an event means that all keys not required by the protocol are stripped off, allowing admins to remove offensive or illegal content that may have been attached to any event. This cannot be undone, allowing server owners to physically delete the offending data. There is also a concept of a moderator hiding a message event, which can be undone, but cannot be applied to state events. The event that has been redacted is specified in the ``redacts`` event level key.", "allOf": [{ "$ref": "core#/definitions/room_event" @@ -11,12 +11,14 @@ "type": "object", "properties": { "reason": { - "type": "string" + "type": "string", + "description": "The reason for the redaction, if any." } } }, "redacts": { - "type": "string" + "type": "string", + "description": "The event ID that was redacted." }, "type": { "type": "string", diff --git a/event-schemas/schema/v1/m.room.topic b/event-schemas/schema/v1/m.room.topic index b3fc4574..4849b229 100644 --- a/event-schemas/schema/v1/m.room.topic +++ b/event-schemas/schema/v1/m.room.topic @@ -1,7 +1,7 @@ { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", - "title": "Set a topic for the room.", + "title": "Topic", "description": "A topic is a short message detailing what is currently being discussed in the room. It can also be used as a way to display extra information about the room, which may not be suitable for the room name. The room topic can also be set when creating a room using ``/createRoom`` with the ``topic`` key.", "allOf": [{ "$ref": "core#/definitions/state_event" @@ -11,7 +11,8 @@ "type": "object", "properties": { "topic": { - "type": "string" + "type": "string", + "description": "The topic text." } }, "required": ["topic"]