Fix xap docs gen + clarify some broadcast messages

data/templates/xap/docs/broadcast_messages.md.j2

@@ -1,4 +1,4 @@
-{%- for id, message in xap.broadcast_messages.messages | dictsort %}
+{% for id, message in xap.broadcast_messages.messages | dictsort %}
 ### {{ message.name }} - `{{ id }}`
 {{ message.description }}
-{%- endfor %}
+{% endfor %}

data/templates/xap/docs/docs.md.j2

@@ -1,9 +1,11 @@
 {{ constants.GPL2_HEADER_XML_LIKE }}
 {{ constants.GENERATED_HEADER_XML_LIKE }}
-{%- for item in xap.documentation.order -%}
-{%- if not item[0:1] == '!' -%}
+{%- for item in xap.documentation.order %}
+{% if not item[0:1] == '!' %}
 {{ xap.documentation.get(item) }}
+
 {% else %}
-{%- include item[1:] %}
+{% include item[1:] %}
+
 {% endif %}
 {% endfor %}

data/templates/xap/docs/response_flags.md.j2

@@ -1,9 +1,12 @@
 |{% for bitnum, bitinfo in xap.response_flags.bits | dictsort | reverse %} Bit {{ bitnum }} |{% endfor %}
+
 |{% for bitnum, bitinfo in xap.response_flags.bits | dictsort | reverse %} -- |{% endfor %}
-|{% for bitnum, bitinfo in xap.response_flags.bits | dictsort | reverse %} `{{ bitinfo.define }}` |{%- endfor %}
+
+|{% for bitnum, bitinfo in xap.response_flags.bits | dictsort | reverse %} `{{ bitinfo.define }}` |{% endfor %}
+
 
 {% for bitnum, bitinfo in xap.response_flags.bits | dictsort | reverse %}
-{%- if bitinfo.define != "-" -%}
+{% if bitinfo.define != "-" -%}
 * Bit {{ bitnum }} (`{{ bitinfo.define }}`): {{ bitinfo.description }}
 {% endif %}
-{%- endfor %}
+{% endfor %}

data/templates/xap/docs/routes.md.j2

@@ -17,20 +17,20 @@ __{{ name }}:__ `{{ type }}`
 {% if 'secure' == route.permissions %}__Secure__{% endif %}
 {%- endmacro -%}
 
-{%- for id, route in xap.routes | dictsort %}
+{% for id, route in xap.routes | dictsort %}
 ### {{ route.name }} - `{{ id }}`
 {{ route.description }}
 
 {% if route.routes %}
 | Name | Route | Tags | Payloads | Description |
 | -- | -- | -- | -- | -- |
-{%- for subid, subroute in route.routes | dictsort %}
-{%- if not subroute.routes %}
+{% for subid, subroute in route.routes | dictsort %}
+{% if not subroute.routes %}
 | {{ subroute.name }} | `{{ id }} {{ subid }}` | {{ gen_tags(subroute) }} | {{ gen_payloads(subroute) }} | {{ subroute.description | newline_to_br }}|
-{%- endif %}
-{%- endfor %}
+{% endif %}
+{% endfor %}
 
-{%- for subid, subroute in route.routes | dictsort %}
+{% for subid, subroute in route.routes | dictsort %}
 {%- if subroute.routes %}
 
 #### {{ subroute.name }} - `{{ id }} {{ subid }}`
@@ -38,12 +38,13 @@ __{{ name }}:__ `{{ type }}`
 
 | Name | Route | Tags | Payloads | Description |
 | -- | -- | -- | -- | -- |
-{%- for subsubid, subsubroute in subroute.routes | dictsort %}
-{%- if not subsubroute.routes %}
+{% for subsubid, subsubroute in subroute.routes | dictsort %}
+{% if not subsubroute.routes %}
 | {{ subsubroute.name }} | `{{ id }} {{ subid }} {{ subsubid }}` | {{ gen_tags(subsubroute) }} | {{ gen_payloads(subsubroute) }} | {{ subsubroute.description | newline_to_br }}|
-{%- endif %}
-{%- endfor %}
-{%- endif %}
-{%- endfor %}
 {% endif %}
-{%- endfor %}
+{% endfor %}
+
+{% endif %}
+{% endfor %}
+{% endif %}
+{% endfor %}

data/templates/xap/docs/term_definitions.md.j2

@@ -1,8 +1,8 @@
 | Name | Definition |
 | -- | -- |
-{%- for type, definition in xap.term_definitions | dictsort %}
+{% for type, definition in xap.term_definitions | dictsort %}
 | _{{ type }}_ | {{ definition }} |
-{%- endfor %}
-{%- for type, definition in xap.type_definitions | dictsort %}
+{% endfor %}
+{% for type, definition in xap.type_definitions | dictsort %}
 | _{{ definition.name }}_ | {{ definition.description }}{% if 'struct' == definition.type %} Takes the format:{% for item in definition.struct_members %}<br>`{{ item.type }}` - {{ item.name }}{%- endfor %}{% endif %} |
-{%- endfor %}
+{% endfor %}

data/templates/xap/docs/type_docs.md.j2

@@ -1,5 +1,5 @@
 | Name | Definition |
 | -- | -- |
-{%- for type, definition in xap.type_docs | dictsort %}
+{% for type, definition in xap.type_docs | dictsort %}
 | _{{ type }}_ | {{ definition }} |
-{%- endfor %}
+{% endfor %}

data/xap/xap_0.1.0.hjson

@@ -20,7 +20,7 @@
             '''
             ## Broadcast messages
 
-            Broadcast messages may be sent by the firmware to the host, without a corresponding inbound request. Each broadcast message uses the token `0xFFFF`, and does not expect a response from the host. Tokens are followed by an _ID_ signifying the type of broadcast, with corresponding _payload_.
+            Broadcast messages may be sent by the firmware to the host, without a corresponding inbound request. Each broadcast message uses the token `0xFFFF`, and does not expect a response from the host. Tokens are followed by an _ID_ signifying the type of broadcast, then the response _payload_ length, and finally the corresponding _payload_.
             '''
     }
 
@@ -100,7 +100,7 @@
                     '''
                     Replicates and replaces the same functionality as if using the standard QMK `CONSOLE_ENABLE = yes` in `rules.mk`. Normal prints within the firmware will manifest as log messages broadcast to the host. `hid_listen` will not be functional with XAP enabled.
 
-                    Log message payloads include a `u8` signifying the length of the text, followed by the `u8[Length]` containing the text itself.
+                    Log message payloads include `u8[Length]` containing the text, where the length of the text is the _broadcast_header.length_ field.
 
                     **Example Log Broadcast** -- log message "Hello QMK!"
 
@@ -119,10 +119,10 @@
 
                     **Example Secure Status Broadcast** -- secure "Unlocking"
 
-                    | Byte | 0 | 1 | 2 | 3 |
-                    | --- | --- | --- | --- | --- |
-                    | **Purpose** | Token | Token | Broadcast Type | Secure Status |
-                    | **Value** | `0xFF` | `0xFF` | `0x01` | `0x01` |
+                    | Byte | 0 | 1 | 2 | 3 | 4 |
+                    | --- | --- | --- | --- | --- | --- |
+                    | **Purpose** | Token | Token | Broadcast Type | Length | Secure Status |
+                    | **Value** | `0xFF` | `0xFF` | `0x01` | `0x01` | `0x01` |
                     '''
                 return_type: u8
             }