Merge pull request #2132 from jimmycuadra/clarify-m.key.verification.start

Clarify the distinction between *m.key.verification.start* and its *m.sas.v1* variant.

changelogs/client_server/newsfragments/2132.clarification

@@ -0,0 +1 @@
+Clarify the distinction between ``m.key.verification.start`` and its ``m.sas.v1`` variant.

event-schemas/schema/m.key.verification.start

@@ -3,7 +3,9 @@ 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:
@@ -26,7 +28,8 @@ properties:
         type: string
         description: |-
           Optional method to use to verify the other user's key with. Applicable
-          when the ``method`` chosen only verifies one user's key.
+          when the ``method`` chosen only verifies one user's key. This field will
+          never be present if the ``method`` verifies keys both ways.
     required:
       - from_device
       - transaction_id

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 a SAS key verification process using the ``m.sas.v1`` method. Typically sent as a `to-device`_ event.
 properties:
   content:
     properties:
@@ -22,7 +22,7 @@ properties:
         type: string
         enum: ["m.sas.v1"]
         description: |-
-          The verification method to use. Must be ``m.sas.v1``.
+          The verification method to use.
       key_agreement_protocols:
         type: array
         description: |-

scripts/templating/matrix_templates/units.py

@@ -902,6 +902,14 @@ 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(