Fix Doxygen wire-format rendering, unify internal constants, and add misalignment tests (#9)

## Pull Request

### Description

Systematic quality sweep across generated headers, Jinja2 templates,
Python tooling, and C tests to resolve naming inconsistencies, improve
Doxygen output, harden the code generator, and expand test coverage.

1. **`ROOT_SIZE` → `J2735_BW_*` constant unification:** Removed
per-header `J2735_INTERNAL_ROOT_SIZE_<TYPE>` constants from all 15
non-extensible DE headers. `_RAW_READ` and `_SIZE` macros now reference
the canonical `J2735_BW_*` constants from `J2735_internal_constants.h`,
eliminating the dual-name problem.
2. **`_Static_assert` for non-extensible DE headers:** Added
compile-time assertions to 7 non-extensible DE headers that were missing
them, ensuring the root bitstring size matches the `J2735_BW_*` constant
at compile time.
3. **Doxygen wire-format tag fixes:** Replaced `@code`/`@endcode` with
`@verbatim`/`@endverbatim` for ASCII-art wire diagrams across all 15 DE
headers and 4 DF headers (Doxygen was mangling box-drawing characters as
C code). Added `@par` section prefixes for proper Doxygen section
grouping.
4. **Hex range width normalization:** Updated
`bitstring_internal_get_all.j2` template to derive hex format width from
`return_type`, fixing 10 headers where `uint8_t` return types
incorrectly showed `0x0000–0x00FF` instead of `0x00–0xFF`.
5. **Jinja2 filter ASN.1 hyphen support:** Extended
`filter_screaming_snake()` and `filter_snake_case()` to handle
hyphenated ASN.1 names (e.g., `Offset-B10` → `OFFSET_B_10`,
`Node-LL-24B` → `NODE_LL_24_B`) with 4 new doctests.
6. **`_sum_field_bits()` validation:** Replaced silent `None → 0`
coercion with an explicit `ValueError` for unresolved field types,
preventing silent corruption of wire-format calculations.
7. **Python code quality:** Replaced `hasattr`/`getattr` chains with
`isinstance` checks in `filter_format_range()` and `filter_is_signed()`;
added `@lru_cache` to `create_jinja_env()`; added `StrictUndefined` to
the Jinja2 environment; replaced magic numbers `1`/`7` with
`_UPER_EXTENSION_MARKER_BITS`/`_UPER_NSNNWN_SMALL_BITS` named constants.
8. **Misalignment tests:** Added
`test_vehicle_event_flags_misaligned_access()` and 3 UPER misalignment
tests (`read_length_determinant`, `read_nsnnwn`, `skip_extensions`) per
testing standards requirement.
9. **Template documentation unification:** Unified docstring format
across all bitstring Jinja2 templates to use consistent `Context
variables:`/`Filters used:`/`Output format:` sections.
10. **License header template for `.j2` files:** Added explicit Jinja2
template example to `license_header.instructions.md` and normalized
indentation in 6 bitstring templates.
11. **Test cleanup:** Removed redundant per-line `cppcheck-suppress`
comments in 4 DF test files (replaced with block-level
`cppcheck-suppress-begin`/`end`); removed unused `<inttypes.h>` and
`<stdbool.h>` includes from 5 DF/UPER test files; clarified test header
`@brief` descriptions across 15 DE test headers.
12. **`asn1_definition.j2` unification:** Generalized the ASN.1
definition template to handle SEQUENCE, CHOICE, and BIT STRING via
`typedef.type_class.name` branching; removed inline ASN.1 blocks from
`assemble_df_choice.j2` and `assemble_de_bitstring.j2`.
13. **Minor fixes:** Renamed `_TEMPLATE_NAME` →
`_SIZE_CONSTANTS_TEMPLATE_NAME` for consistency with other module-level
constants; added `kw_only=True` to 2 wire-format dataclasses; split long
`@note` box lines in `assemble_de_bitstring.j2`.

### Related Issue

N/A

### Additional Notes

N/A

### Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Performance improvement

### Checklist

- [x] My code follows the project's zero-copy coding style
- [x] I have read the [CONTRIBUTING.md](../CONTRIBUTING.md) guidelines
- [x] I have added/updated documentation as needed
- [x] I have added tests that prove my fix/feature works
- [x] I have run `make pre-push` and all checks pass
- [x] I have signed my commits (DCO) using `git commit -s`

---------

Signed-off-by: Yogev Neumann <xqgex@users.noreply.github.com>

Author: xqgex

.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.