make code required, and some more details about no_olm

proposals/2399-reporting-no-key-sent.md

@@ -31,7 +31,7 @@ the properties:
 - `algorithm`: Required. The encryption algorithm that the key is for.
 - `session_id`: Required if `code` is not `m.no_olm`. The ID of the session.
 - `sender_key`: Required.  The key of the session creator.
-- `code`: A machine-readable code for why the key was not sent.
+- `code`: Required.  A machine-readable code for why the key was not sent.
   Possible values are:
   - `m.blacklisted`: the user/device was blacklisted
   - `m.unverified`: the user/devices is unverified
@@ -43,10 +43,9 @@ the properties:
   - `m.no_olm`: an olm session could not be established.  This may happen, for
     example, if the sender was unable to obtain a one-time key from the
     recipient.
-- `reason`: A human-readable reason for why the key was not sent.  If there is
+- `reason`: A human-readable reason for why the key was not sent.  The
-  a `code`, this should be a human-readable representation of `code`.  The
   receiving client should only use this string if it does not understand the
-  `code` or if `code` is not provided.
+  `code`.
 
 An `m.room_key.withheld` event should only be sent once per session; the
 recipient of the event should assume that the event applies to all messages in
@@ -60,8 +59,11 @@ A `code` of `m.no_olm` is used to indicate that the sender is unable to
 establish an olm session with the recipient.  When this happens, multiple
 sessions will be affected.  In order to avoid filling the recipient's device
 mailbox, the sender should only send one `m.room_key.withheld` message with no
-`room_id` nor `session_id` set.  FIXME: how does the recipient determine which
+`room_id` nor `session_id` set.  In response to receiving this message, the
-sessions the notification applies to?
+recipient may start an olm session with the sender, and send an `m.dummy`
+message to notify the sender of the new olm session.  The recipient may assume
+that this `m.room_key.withheld` message applies to all encrypted room messages
+sent before it receives the message.
 
 ## Potential issues
 
@@ -71,8 +73,7 @@ megolm keys.
 ## Security considerations
 
 A user might not want to notify another user of the reason why it was not sent
-the keys.  Sending `m.room_key.withheld`, or specifying the `reason`/`code` are
+the keys.  Sending `m.room_key.withheld` is optional.
-optional.
 
 ## Unstable prefix