docs: describe messages, example of sequence of messages

Sponsored-by: author

1 files changed, 84 insertions, 5 deletions

diff --git a/README.md b/README.md
index 4c0dfc6..0d5e25b 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,14 @@ with result it has come up with.
 
 ## Client request: start computation
 
+Client starts the protocol by asking the server to compute something
+about a list of numbers the client holds. It tells the server what
+computation is requested, and how long the list is.
+
+The supported computations are, for now, `compute_max` (find index of
+the largest integer) and `compute_min` (similar, but smallest
+integer).
+
 ~~~json
 {
     "type": "compute_max",
@@ -34,6 +42,9 @@ with result it has come up with.
 
 ## Server response: request computation
 
+Server ask the client to report the result of a less-than comparison
+operation between arbitrary list items.
+
 ~~~json
 {
     "type": "compare",
@@ -45,6 +56,10 @@ with result it has come up with.
 
 ## Client request: computation result
 
+The client reports the result of a comparison. The server should
+respond by another comparison request, or the result of the
+computation.
+
 ~~~json
 {
     "type": "comp_result",
@@ -64,20 +79,84 @@ with result it has come up with.
 
 # Example
 
+In this example, assume the client has the following list:
+
+> 5, 6, 7, 5
+
+Note that the list is not in order and numbers aren't unique. The
+sequence diagram below shows the messages the go between the client
+and the server.
+
+For simplicity, request ids are not shown.
+
 ~~~plantuml
 @startuml
 
-Alice -> Bob: Authentication Request
-Bob --> Alice: Authentication Response
-
-Alice -> Bob: Another authentication Request
+participant "client" as c
+participant "server" as s
+
+c -> s : compute_max, length=4
+note left
+client tells server there 
+are 4 integes and that the
+server should figure out
+the largest one
+end note
+
+c <- s : compare(0,1)
+note right
+server wants client to
+compare integers at
+indexes 0 and 1
+end note
+
+c -> s : comp_result, answer=true
+note left
+client reports that
+the integer at index
+0 is less than the one
+at index 1
+end note
+
+c <- s : compare(1,2)
+note right
+max so far is at index 1;
+server asks is list[1] < list[2]
+end note
+
+c -> s : comp_result, answer=true
+note left
+client reports yes
+end note
+
+c <- s : compare(2,3)
+note right
+max so far is at index 2;
+server asks is list[2] < list[3]
+end note
+
+c -> s : comp_result, answer=false
+note left
+client reports no
+end note
+
+c <- s : done, answer=2
+note right
+server knows it has compared
+all list items and that max is
+at index 2
+end note
 
 @enduml
 ~~~
 
+This is very simple computation. Given the server can't assume the
+list is ordered, it has to compare all list elements to the largest
+one it has found so far.
+
 
 ---
-title: OSO work sample
+title: "OSO work sample&mdash;MAX"
 author: Lars Wirzenius
 classes:
 - json