Fix Doxygen wire-format rendering, unify internal constants, and add misalignment tests

.github/instructions/license_header.instructions.md

@@ -31,6 +31,7 @@ Use Doxygen comments.
  * SPDX-License-Identifier: Apache-2.0
  * SPDX-FileCopyrightText: 2026 Yogev Neumann
  */
+<THE REST OF THE FILE>
 ```
 
 ### Python / YAML / Makefile / Shell / Gitignore
@@ -54,12 +55,34 @@ Use hash comments.
 #
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: 2026 Yogev Neumann
-<THE REST OF THE FILE>>
+<THE REST OF THE FILE>
 ```
 
-### Jinja2 Templates
+### Jinja2 `.j2` Templates
 
-Templates should also have the license as a comment at the top of each file wrapped with `{#-` and `-#}`.
+Use a comment at the top of each file wrapped with `{#-` and `-#}`.
+
+```jinja2
+{#-
+  Copyright 2026 Yogev Neumann
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+
+  SPDX-License-Identifier: Apache-2.0
+  SPDX-FileCopyrightText: 2026 Yogev Neumann
+-#}
+<THE REST OF THE FILE>
+```
 
 ## Exceptions
 

src/J2735_internal_DE_AllowedManeuvers.h

@@ -21,6 +21,7 @@
  * @author Yogev Neumann
  * @brief J2735 AllowedManeuvers Definition and Access Macros.
  *
+ * @verbatim
  * AllowedManeuvers ::= BIT STRING {
  *     maneuverStraightAllowed (0),
  *     maneuverLeftAllowed (1),
@@ -35,46 +36,42 @@
  *     caution (10),
  *     reserved1 (11)
  * } (SIZE (12))
+ * @endverbatim
  *
  * Fixed BIT STRING with size 12.
  *
- * Wire Format (12 bits total):
+ * @par Wire Format (12 bits total):
+ * @verbatim
  * ┌──────────────────────────────────────────────────────────────┐
  * │ Bits 0-11                                                    │
  * ├──────────────────────────────────────────────────────────────┤
  * │ flags[0..11] (12 bits)                                       │
  * └──────────────────────────────────────────────────────────────┘
+ * @endverbatim
  *
- * Optimization: Single-Read Strategy
- * ──────────────────────────────────────────────────────────────────────────────────────────
+ * @par Optimization: Single-Read Strategy
+ * @verbatim
  * Max wire size = 12 bits ≤ 56-bit READ_BITS limit.
  * We read all 12 bits in ONE call, then use bit arithmetic to extract:
  *   - Flags at positions 0-11
  *
  * 12-bit read layout (left-justified from bit 0):
  *   [F0..F11] (12 flag bits, no extension marker)
+ * @endverbatim
  */
 #ifndef J2735_INTERNAL_DE_ALLOWEDMANEUVERS_H
 #define J2735_INTERNAL_DE_ALLOWEDMANEUVERS_H
 
 #include "J2735_internal_common.h"
 
-/* ============================================================================================== */
-/*  Constants                                                                                     */
-/* ============================================================================================== */
-/**
- * @internal
- * @brief Root size of AllowedManeuvers in bits.
- */
-#define J2735_INTERNAL_ROOT_SIZE_ALLOWED_MANEUVERS 12U
-
 /* ============================================================================================== */
 /*  INTERNAL: Bit Position Constants                                                              */
 /*                                                                                                */
 /*  ASN.1 BIT STRING numbering convention: bit 0 = MSB (leftmost in wire order).                  */
 /*  These constants map semantic flag names to their ASN.1 bit positions.                         */
 /*                                                                                                */
-/*  @note Internal use only. Use the public J2735_ALLOWED_MANEUVERS_GET_*() accessors instead.    */
+/*  @note Internal use only.                                                                      */
+/*  Use the public J2735_ALLOWED_MANEUVERS_GET_*() accessors instead.                             */
 /* ============================================================================================== */
 #define J2735_INTERNAL_BIT_ALLOWED_MANEUVERS_MANEUVER_STRAIGHT_ALLOWED          0U
 #define J2735_INTERNAL_BIT_ALLOWED_MANEUVERS_MANEUVER_LEFT_ALLOWED              1U
@@ -107,7 +104,7 @@
  * @note Internal use only. Not part of the public API.
  */
 #define J2735_INTERNAL_RAW_READ_ALLOWED_MANEUVERS(buf)                                             \
-  J2735_READ_BITS((buf), 0U, J2735_INTERNAL_ROOT_SIZE_ALLOWED_MANEUVERS)
+  J2735_READ_BITS((buf), 0U, J2735_BW_ALLOWED_MANEUVERS)
 
 /* ============================================================================================== */
 /*  INTERNAL: Extension Bit Check                                                                 */
@@ -174,7 +171,7 @@
  * @param[in] buf Pointer to the start of the AllowedManeuvers UPER encoding (const uint8_t*).
  * @return Always 12U.
  */
-#define J2735_ALLOWED_MANEUVERS_SIZE(buf) ((void)(buf), J2735_INTERNAL_ROOT_SIZE_ALLOWED_MANEUVERS)
+#define J2735_ALLOWED_MANEUVERS_SIZE(buf) ((void)(buf), J2735_BW_ALLOWED_MANEUVERS)
 
 /**
  * @brief Get all AllowedManeuvers as a single uint16_t value.

src/J2735_internal_DE_BrakeAppliedStatus.h

@@ -21,53 +21,50 @@
  * @author Yogev Neumann
  * @brief J2735 BrakeAppliedStatus Definition and Access Macros.
  *
+ * @verbatim
  * BrakeAppliedStatus ::= BIT STRING {
  *     unavailable (0),
  *     leftFront (1),
  *     leftRear (2),
  *     rightFront (3),
  *     rightRear (4)
  * } (SIZE (5))
+ * @endverbatim
  *
  * Fixed BIT STRING with size 5.
  *
- * Wire Format (5 bits total):
+ * @par Wire Format (5 bits total):
+ * @verbatim
  * ┌──────────────────────────────────────────────────────────────┐
  * │ Bits 0-4                                                     │
  * ├──────────────────────────────────────────────────────────────┤
  * │ flags[0..4] (5 bits)                                         │
  * └──────────────────────────────────────────────────────────────┘
+ * @endverbatim
  *
- * Optimization: Single-Read Strategy
- * ──────────────────────────────────────────────────────────────────────────────────────────
+ * @par Optimization: Single-Read Strategy
+ * @verbatim
  * Max wire size = 5 bits ≤ 56-bit READ_BITS limit.
  * We read all 5 bits in ONE call, then use bit arithmetic to extract:
  *   - Flags at positions 0-4
  *
  * 5-bit read layout (left-justified from bit 0):
  *   [F0..F4] (5 flag bits, no extension marker)
+ * @endverbatim
  */
 #ifndef J2735_INTERNAL_DE_BRAKEAPPLIEDSTATUS_H
 #define J2735_INTERNAL_DE_BRAKEAPPLIEDSTATUS_H
 
 #include "J2735_internal_common.h"
 
-/* ============================================================================================== */
-/*  Constants                                                                                     */
-/* ============================================================================================== */
-/**
- * @internal
- * @brief Root size of BrakeAppliedStatus in bits.
- */
-#define J2735_INTERNAL_ROOT_SIZE_BRAKE_APPLIED_STATUS 5U
-
 /* ============================================================================================== */
 /*  INTERNAL: Bit Position Constants                                                              */
 /*                                                                                                */
 /*  ASN.1 BIT STRING numbering convention: bit 0 = MSB (leftmost in wire order).                  */
 /*  These constants map semantic flag names to their ASN.1 bit positions.                         */
 /*                                                                                                */
-/*  @note Internal use only. Use the public J2735_BRAKE_APPLIED_STATUS_GET_*() accessors instead. */
+/*  @note Internal use only.                                                                      */
+/*  Use the public J2735_BRAKE_APPLIED_STATUS_GET_*() accessors instead.                          */
 /* ============================================================================================== */
 #define J2735_INTERNAL_BIT_BRAKE_APPLIED_STATUS_UNAVAILABLE 0U
 #define J2735_INTERNAL_BIT_BRAKE_APPLIED_STATUS_LEFT_FRONT  1U
@@ -93,7 +90,7 @@
  * @note Internal use only. Not part of the public API.
  */
 #define J2735_INTERNAL_RAW_READ_BRAKE_APPLIED_STATUS(buf)                                          \
-  J2735_READ_BITS((buf), 0U, J2735_INTERNAL_ROOT_SIZE_BRAKE_APPLIED_STATUS)
+  J2735_READ_BITS((buf), 0U, J2735_BW_BRAKE_APPLIED_STATUS)
 
 /* ============================================================================================== */
 /*  INTERNAL: Extension Bit Check                                                                 */
@@ -119,7 +116,7 @@
  *
  * @param[in] raw5 Value previously returned by J2735_INTERNAL_RAW_READ_BRAKE_APPLIED_STATUS().
  * @return Right-aligned flag bits as uint8_t:
- *         - 5 significant bits (0x0000-0x001F)
+ *         - 5 significant bits (0x00-0x1F)
  * @note Internal use only. Use J2735_BRAKE_APPLIED_STATUS_GET() for public API.
  */
 #define J2735_INTERNAL_GET_ALL_BRAKE_APPLIED_STATUS(raw5) ((uint8_t)((raw5) & 0x1FU))
@@ -160,8 +157,7 @@
  * @param[in] buf Pointer to the start of the BrakeAppliedStatus UPER encoding (const uint8_t*).
  * @return Always 5U.
  */
-#define J2735_BRAKE_APPLIED_STATUS_SIZE(buf)                                                       \
-  ((void)(buf), J2735_INTERNAL_ROOT_SIZE_BRAKE_APPLIED_STATUS)
+#define J2735_BRAKE_APPLIED_STATUS_SIZE(buf) ((void)(buf), J2735_BW_BRAKE_APPLIED_STATUS)
 
 /**
  * @brief Get all BrakeAppliedStatus as a single uint8_t value.

src/J2735_internal_DE_ExteriorLights.h

@@ -21,6 +21,7 @@
  * @author Yogev Neumann
  * @brief J2735 ExteriorLights Definition and Access Macros.
  *
+ * @verbatim
  * ExteriorLights ::= BIT STRING {
  *     lowBeamHeadlightsOn (0),
  *     highBeamHeadlightsOn (1),
@@ -32,25 +33,30 @@
  *     fogLightOn (7),
  *     parkingLightsOn (8)
  * } (SIZE (9, ...))
+ * @endverbatim
  *
  * Extensible BIT STRING with root size 9 and known extension size 9.
  *
- * Wire Format (non-extended, 10 bits total):
+ * @par Wire Format (non-extended, 10 bits total):
+ * @verbatim
  * ┌───────┬──────────────────────────────────────────────────────┐
  * │ Bit 0 │ Bits 1-9                                             │
  * ├───────┼──────────────────────────────────────────────────────┤
  * │ Ext=0 │ flags[0..8] (9 bits)                                 │
  * └───────┴──────────────────────────────────────────────────────┘
+ * @endverbatim
  *
- * Wire Format (extended, 17 bits total):
+ * @par Wire Format (extended, 17 bits total):
+ * @verbatim
  * ┌───────┬────────────────────┬─────────────────────────────────┐
  * │ Bit 0 │ Bits 1-7           │ Bits 8-16                       │
  * ├───────┼────────────────────┼─────────────────────────────────┤
  * │ Ext=1 │ nsnnwn=9 (7 bits)  │ flags[0..8] (9 bits)            │
  * └───────┴────────────────────┴─────────────────────────────────┘
+ * @endverbatim
  *
- * Optimization: Single-Read Strategy
- * ──────────────────────────────────────────────────────────────────────────────────────────
+ * @par Optimization: Single-Read Strategy
+ * @verbatim
  * Max wire size = 17 bits ≤ 56-bit READ_BITS limit.
  * We read all 17 bits in ONE call, then use bit arithmetic to extract:
  *   - Extension bit at position 16 (MSB of 17-bit value)
@@ -61,6 +67,7 @@
  *                  bit16  15..7     6..0
  *   Extended:     [Ext=1][nsnnwn:7][F0..F8]
  *                  bit16  15..9    8..0
+ * @endverbatim
  */
 #ifndef J2735_INTERNAL_DE_EXTERIORLIGHTS_H
 #define J2735_INTERNAL_DE_EXTERIORLIGHTS_H
@@ -102,7 +109,8 @@ _Static_assert(J2735_INTERNAL_MAX_WIRE_BITS_EXTERIOR_LIGHTS ==
 /*  ASN.1 BIT STRING numbering convention: bit 0 = MSB (leftmost in wire order).                  */
 /*  These constants map semantic flag names to their ASN.1 bit positions.                         */
 /*                                                                                                */
-/*  @note Internal use only. Use the public J2735_EXTERIOR_LIGHTS_GET_*() accessors instead.      */
+/*  @note Internal use only.                                                                      */
+/*  Use the public J2735_EXTERIOR_LIGHTS_GET_*() accessors instead.                               */
 /* ============================================================================================== */
 #define J2735_INTERNAL_BIT_EXTERIOR_LIGHTS_LOW_BEAM_HEADLIGHTS_ON     0U
 #define J2735_INTERNAL_BIT_EXTERIOR_LIGHTS_HIGH_BEAM_HEADLIGHTS_ON    1U

src/J2735_internal_DE_GNSSstatus.h

@@ -21,6 +21,7 @@
  * @author Yogev Neumann
  * @brief J2735 GNSSstatus Definition and Access Macros.
  *
+ * @verbatim
  * GNSSstatus ::= BIT STRING {
  *     unavailable (0),
  *     isHealthy (1),
@@ -31,46 +32,42 @@
  *     localCorrectionsPresent (6),
  *     networkCorrectionsPresent (7)
  * } (SIZE (8))
+ * @endverbatim
  *
  * Fixed BIT STRING with size 8.
  *
- * Wire Format (8 bits total):
+ * @par Wire Format (8 bits total):
+ * @verbatim
  * ┌──────────────────────────────────────────────────────────────┐
  * │ Bits 0-7                                                     │
  * ├──────────────────────────────────────────────────────────────┤
  * │ flags[0..7] (8 bits)                                         │
  * └──────────────────────────────────────────────────────────────┘
+ * @endverbatim
  *
- * Optimization: Single-Read Strategy
- * ──────────────────────────────────────────────────────────────────────────────────────────
+ * @par Optimization: Single-Read Strategy
+ * @verbatim
  * Max wire size = 8 bits ≤ 56-bit READ_BITS limit.
  * We read all 8 bits in ONE call, then use bit arithmetic to extract:
  *   - Flags at positions 0-7
  *
  * 8-bit read layout (left-justified from bit 0):
  *   [F0..F7] (8 flag bits, no extension marker)
+ * @endverbatim
  */
 #ifndef J2735_INTERNAL_DE_GNSSSTATUS_H
 #define J2735_INTERNAL_DE_GNSSSTATUS_H
 
 #include "J2735_internal_common.h"
 
-/* ============================================================================================== */
-/*  Constants                                                                                     */
-/* ============================================================================================== */
-/**
- * @internal
- * @brief Root size of GNSSstatus in bits.
- */
-#define J2735_INTERNAL_ROOT_SIZE_GNSS_STATUS 8U
-
 /* ============================================================================================== */
 /*  INTERNAL: Bit Position Constants                                                              */
 /*                                                                                                */
 /*  ASN.1 BIT STRING numbering convention: bit 0 = MSB (leftmost in wire order).                  */
 /*  These constants map semantic flag names to their ASN.1 bit positions.                         */
 /*                                                                                                */
-/*  @note Internal use only. Use the public J2735_GNSS_STATUS_GET_*() accessors instead.          */
+/*  @note Internal use only.                                                                      */
+/*  Use the public J2735_GNSS_STATUS_GET_*() accessors instead.                                   */
 /* ============================================================================================== */
 #define J2735_INTERNAL_BIT_GNSS_STATUS_UNAVAILABLE                 0U
 #define J2735_INTERNAL_BIT_GNSS_STATUS_IS_HEALTHY                  1U
@@ -98,8 +95,7 @@
  * @return 8-bit value as uint64_t with wire bits left-justified.
  * @note Internal use only. Not part of the public API.
  */
-#define J2735_INTERNAL_RAW_READ_GNSS_STATUS(buf)                                                   \
-  J2735_READ_BITS((buf), 0U, J2735_INTERNAL_ROOT_SIZE_GNSS_STATUS)
+#define J2735_INTERNAL_RAW_READ_GNSS_STATUS(buf) J2735_READ_BITS((buf), 0U, J2735_BW_GNSS_STATUS)
 
 /* ============================================================================================== */
 /*  INTERNAL: Extension Bit Check                                                                 */
@@ -125,7 +121,7 @@
  *
  * @param[in] raw8 Value previously returned by J2735_INTERNAL_RAW_READ_GNSS_STATUS().
  * @return Right-aligned flag bits as uint8_t:
- *         - 8 significant bits (0x0000-0x00FF)
+ *         - 8 significant bits (0x00-0xFF)
  * @note Internal use only. Use J2735_GNSS_STATUS_GET() for public API.
  */
 #define J2735_INTERNAL_GET_ALL_GNSS_STATUS(raw8) ((uint8_t)((raw8) & 0xFFU))
@@ -166,7 +162,7 @@
  * @param[in] buf Pointer to the start of the GNSSstatus UPER encoding (const uint8_t*).
  * @return Always 8U.
  */
-#define J2735_GNSS_STATUS_SIZE(buf) ((void)(buf), J2735_INTERNAL_ROOT_SIZE_GNSS_STATUS)
+#define J2735_GNSS_STATUS_SIZE(buf) ((void)(buf), J2735_BW_GNSS_STATUS)
 
 /**
  * @brief Get all GNSSstatus as a single uint8_t value.