From bc71dacaf4f65e2a27705a658fc4b303ecba16c9 Mon Sep 17 00:00:00 2001
From: Jimmy Cuadra <jimmy@jimmycuadra.com>
Date: Fri, 14 Jun 2019 16:05:25 -0700
Subject: [PATCH] Clarify the distinction between *m.key.verification.start*
 and its *m.sas.v1* variant.

Currently the *m.key.verification.start* event appears twice with the
exact same title, in the "Key verification framework" section and the
"Short Authentication (SAS) verification" section. It's not immediately
clear that the first occurrence describes the format of the event in
general terms and that the second occurrence describes the fields when
the *m.sas.v1* verification method is being used. This is a similar
relationship to the *m.room.message* event and its various *msgtype*
variants.

This commit does three things:

* It tweaks the generation of the documentation to change the title
  of the second occurrence of *m.key.verification.start* to
  distinguish it from the first.
* It updates the language in the description of the two versions of the
  event to better describe the relationship between the two.
* It adds the optional `next_method` field to the schema of the
  *m.sas.v1* variant, as specified in the general form of
  *m.key.verification.start*.

Signed-off-by: Jimmy Cuadra <jimmy@jimmycuadra.com>
---
 .../client_server/newsfragments/2132.clarification       | 1 +
 event-schemas/schema/m.key.verification.start            | 2 +-
 event-schemas/schema/m.key.verification.start$m.sas.v1   | 8 ++++++--
 scripts/templating/matrix_templates/units.py             | 9 +++++++++
 4 files changed, 17 insertions(+), 3 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/2132.clarification

diff --git a/changelogs/client_server/newsfragments/2132.clarification b/changelogs/client_server/newsfragments/2132.clarification
new file mode 100644
index 00000000..53063400
--- /dev/null
+++ b/changelogs/client_server/newsfragments/2132.clarification
@@ -0,0 +1 @@
+Clarify the distinction between *m.key.verification.start* and its *m.sas.v1* variant.
diff --git a/event-schemas/schema/m.key.verification.start b/event-schemas/schema/m.key.verification.start
index ad59d6c7..99b4998e 100644
--- a/event-schemas/schema/m.key.verification.start
+++ b/event-schemas/schema/m.key.verification.start
@@ -3,7 +3,7 @@ allOf:
   - $ref: core-event-schema/event.yaml
 
 description: |-
-  Begins a key verification process. Typically sent as a `to-device`_ event.
+  Begins a key verification process. Typically sent as a `to-device`_ event. The ``method`` field determines the type of verification. The fields in the event will differ depending on the ``method``. This definition includes fields that are in common among all variants.
 properties:
   content:
     properties:
diff --git a/event-schemas/schema/m.key.verification.start$m.sas.v1 b/event-schemas/schema/m.key.verification.start$m.sas.v1
index 867ca820..a42f20e7 100644
--- a/event-schemas/schema/m.key.verification.start$m.sas.v1
+++ b/event-schemas/schema/m.key.verification.start$m.sas.v1
@@ -3,7 +3,7 @@ allOf:
   - $ref: core-event-schema/event.yaml
 
 description: |-
-  Begins a SAS key verification process. Typically sent as a `to-device`_ event.
+  Begins an SAS key verification process using the ``m.sas.v1`` method. Typically sent as a `to-device`_ event.
 properties:
   content:
     properties:
@@ -22,7 +22,11 @@ properties:
         type: string
         enum: ["m.sas.v1"]
         description: |-
-          The verification method to use. Must be ``m.sas.v1``.
+          The verification method to use.
+      next_method:
+        type: string
+        description: |-
+          Optional method to use to verify the other user's key with.
       key_agreement_protocols:
         type: array
         description: |-
diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py
index 157fa5a1..8538de2d 100644
--- a/scripts/templating/matrix_templates/units.py
+++ b/scripts/templating/matrix_templates/units.py
@@ -902,6 +902,15 @@ class MatrixUnits(Units):
                 "`m.room.message msgtypes`_."
             )
 
+        # method types for m.key.verification.start
+        if schema["type"] == "m.key.verification.start":
+            methods = Units.prop(
+                json_schema, "properties/content/properties/method/enum"
+            )
+            if methods:
+                schema["type_with_msgtype"] = schema["type"] + " (" + methods[0] + ")"
+
+
         # Assign state key info if it has some
         if schema["typeof"] == "State Event":
             skey_desc = Units.prop(