From 980699f3cfd4761c9a2acdbb39d8283a6518694e Mon Sep 17 00:00:00 2001 From: zvecr Date: Tue, 29 Aug 2023 02:37:23 +0100 Subject: [PATCH] Fix xap docs gen + clarify some broadcast messages --- .../xap/docs/broadcast_messages.md.j2 | 4 +- data/templates/xap/docs/docs.md.j2 | 8 ++-- data/templates/xap/docs/response_flags.md.j2 | 9 +++-- data/templates/xap/docs/routes.md.j2 | 27 ++++++------- .../templates/xap/docs/term_definitions.md.j2 | 8 ++-- data/templates/xap/docs/type_docs.md.j2 | 4 +- data/xap/xap_0.1.0.hjson | 12 +++--- docs/xap_0.0.1.md | 5 +-- docs/xap_0.1.0.md | 22 ++++------- docs/xap_0.2.0.md | 25 ++++-------- docs/xap_0.3.0.md | 38 ++++++++++--------- docs/xap_protocol.md | 2 +- 12 files changed, 78 insertions(+), 86 deletions(-) diff --git a/data/templates/xap/docs/broadcast_messages.md.j2 b/data/templates/xap/docs/broadcast_messages.md.j2 index 9e4ca953f1d..bb82c98a0ff 100644 --- a/data/templates/xap/docs/broadcast_messages.md.j2 +++ b/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 %} diff --git a/data/templates/xap/docs/docs.md.j2 b/data/templates/xap/docs/docs.md.j2 index a43b50b8ce6..2233cdb3b00 100644 --- a/data/templates/xap/docs/docs.md.j2 +++ b/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 %} \ No newline at end of file diff --git a/data/templates/xap/docs/response_flags.md.j2 b/data/templates/xap/docs/response_flags.md.j2 index 852db16fd93..3914dbb5a35 100644 --- a/data/templates/xap/docs/response_flags.md.j2 +++ b/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 %} \ No newline at end of file +{% endfor %} \ No newline at end of file diff --git a/data/templates/xap/docs/routes.md.j2 b/data/templates/xap/docs/routes.md.j2 index 92afcad20ba..65a1568f99d 100644 --- a/data/templates/xap/docs/routes.md.j2 +++ b/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 %} diff --git a/data/templates/xap/docs/term_definitions.md.j2 b/data/templates/xap/docs/term_definitions.md.j2 index 9b2863eaa5f..710a9890e97 100644 --- a/data/templates/xap/docs/term_definitions.md.j2 +++ b/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 %}
`{{ item.type }}` - {{ item.name }}{%- endfor %}{% endif %} | -{%- endfor %} \ No newline at end of file +{% endfor %} \ No newline at end of file diff --git a/data/templates/xap/docs/type_docs.md.j2 b/data/templates/xap/docs/type_docs.md.j2 index 787d9428532..4700681274c 100644 --- a/data/templates/xap/docs/type_docs.md.j2 +++ b/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 %} \ No newline at end of file +{% endfor %} \ No newline at end of file diff --git a/data/xap/xap_0.1.0.hjson b/data/xap/xap_0.1.0.hjson index 45402c48614..932d6d09a03 100755 --- a/data/xap/xap_0.1.0.hjson +++ b/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 } diff --git a/docs/xap_0.0.1.md b/docs/xap_0.0.1.md index d94ada81d67..b35acf14790 100644 --- a/docs/xap_0.0.1.md +++ b/docs/xap_0.0.1.md @@ -1,4 +1,4 @@ - + + + + +