From 5bf5670a1d2dfb32e758bb6f0cd810c6e145585f Mon Sep 17 00:00:00 2001
From: Oliver Marks <osmarks@protonmail.com>
Date: Sat, 6 Oct 2018 15:00:57 +0100
Subject: [PATCH] Update PROTOCOL.md

---
 PROTOCOL.md | 62 ++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 52 insertions(+), 10 deletions(-)

diff --git a/PROTOCOL.md b/PROTOCOL.md
index 970cbff..83ae748 100644
--- a/PROTOCOL.md
+++ b/PROTOCOL.md
@@ -3,10 +3,41 @@
 ## General
 
 Connections are by websocket.
-Messages must be JSON-serialized objects containing at least a `type` key (e.g. `{"type": "log"}`) - this key is the command to run.
-Commands take other arguments, passed in that object (e.g. `{"type": "open", "channel": "whatever"}`).
-When a command is executed, it will either return a good result (e.g. `{"type": "result", "for": "log", "log": []}`) or an error (e.g. `{"type": "error", "error": "Human-readable description of error."}`).
-Clients may also receive events, which have a `type` key containing the name of the event and extra data (e.g. `{"type": "message", "channel": 42, "message": "hi"}`).
+Messages must be JSON-serialized objects containing a `type` key, like this:
+```
+{
+  "type": "log"
+}
+```
+Arguments to commands are keys in this object:
+```
+{
+  "type": "open",
+  "channel": 42
+}
+```
+Commands return either results:
+```
+{
+  "type": "result",
+  "channels": [42]
+}
+```
+or errors:
+```
+{
+  "type": "error",
+  "error": "Invalid type for channel!"
+}
+```
+Connected sockets may be sent events, such as:
+```
+{
+  "type": "message",
+  "channel": 42,
+  "message": "Hello, World!"
+}
+```
 
 ## Client
 
@@ -17,25 +48,25 @@ This is the interface `client.lua` uses.
 
 #### open
 
-Takes a `channel` key (channel to open - can be string or number) and opens that channel on the socket sending this command. Opening `*` will listen to messages on all channels.
+Takes `channel` (channel to open - string or number) and opens it for the socket sending this command. Opening `*` will listen to messages on all channels.
 
 Returns `channels`, a list of channels which are now open.
 
 #### close
 
-Takes a `channel` key and closes that channel - opposite of open.
+Takes `channel` and closes it channel - opposite of open.
 
 Returns `channels`, a list of channels which are now open.
 
 #### message
 
-Takes a `message` key (contents of message to send) and `channel` key (channel to send on) and sends the message to all clients listening on the channel used.  See `message` event for further details.
+Takes `message` (contents of message to send) and `channel` (channel to send on) and sends the message to all clients listening on the channel specified.  See `message` event for further details.
 
 Returns the message sent.
 
 #### log
 
-Optionally takes `start` and `end` keys (slice of message log to return).
+Optionally takes `start` and `end` (slice of message log to return).
 
 Returns the server's message log (on all channels); this consists of an array of `message` events.
 The message log is newest-first and not persisted across server restarts.
@@ -44,10 +75,21 @@ The message log is newest-first and not persisted across server restarts.
 
 #### message
 
-This contains all the keys present in the message command which produced it (should always include `channel` and `message`) as well as `time` (as produced by `new Date().getTime()`) and `ID` (unique per-message ID).
+This contains all the information present in the message command which produced it (should always include `channel` and `message`), but also has `time` (as produced by `new Date().getTime()`) and `ID` (unique per-message ID).
 
 These are sent when another client uses the `message` command with a channel your socket is listening on.
 
+Here is an example message:
+```
+{
+  "type": "message",
+  "channel": 42,
+  "message": "Hello, World!",
+  "ID": "cjmxia0pv0000k2t3z8p26cjm",
+  "time": 1538834413603
+}
+```
+
 ## Peer
 
-Coming Soon.
\ No newline at end of file
+Coming Soon.