xqgex · xqgex · Feb 16, 2026 · Feb 16, 2026
@@ -33,7 +33,8 @@ tools/
 **Each test file tests ONE class or ONE closely-related function group.**
 
 - `IntegerConstraint` → `tests/spec/test_integer_constraint.py`
-- `compute_wire_format()` → `tests/c_generator/test_wire_format.py`
+- `get_sequence_variants()` → `tests/c_generator/test_wire_format_variants.py`
+- Wire format templates → `tests/c_generator/test_wire_format_templates.py`
 - New class added? → New test file created.
 
 This ensures files can remain in the target of ~300-500 lines.

@@ -21,6 +21,10 @@
 # Build directory (all build artifacts go here)
 /build/
 
+# Doxygen output
+/html/
+/latex/
+
 # Editor/IDE
 .vscode/
 

@@ -0,0 +1,30 @@
+# Doxyfile 1.9.8
+
+CREATE_SUBDIRS         = YES
+OPTIMIZE_OUTPUT_FOR_C  = YES
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = YES
+EXTRACT_STATIC         = YES
+EXTRACT_LOCAL_METHODS  = YES
+HIDE_UNDOC_MEMBERS     = YES
+HIDE_UNDOC_CLASSES     = YES
+INTERNAL_DOCS          = YES
+WARN_AS_ERROR          = YES
+INPUT                  = ./src
+FILE_PATTERNS          = *.c \
+                         *.h \
+                         *.md
+RECURSIVE              = YES
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = YES
+STRIP_CODE_COMMENTS    = NO
+CLANG_ASSISTED_PARSING = YES
+GENERATE_TREEVIEW      = YES
+MACRO_EXPANSION        = YES
+PREDEFINED             = __GNUC__ \
+                         __clang__ \
+                         J2735_PACK_START= \
+                         J2735_PACK_END=
+CALL_GRAPH             = YES
+CALLER_GRAPH           = YES
+INTERACTIVE_SVG        = YES
@@ -21,77 +21,119 @@
  * @author Yogev Neumann
  * @brief J2735 IntersectionReferenceID Definition and Access Macros.
  *
+ * @par IntersectionReferenceID Wire Format (UPER):
+ * @code
  * IntersectionReferenceID ::= SEQUENCE {
- *     region  RoadRegulatorID OPTIONAL,  -- 16 bits (J2735_BW_ROAD_REGULATOR_ID)
- *     id      IntersectionID             -- 16 bits (J2735_BW_INTERSECTION_ID)
+ *     region        RoadRegulatorID OPTIONAL,  -- 16 bits (unsigned, 0..65535)
+ *     id            IntersectionID             -- 16 bits (unsigned, 0..65535)
  * }
+ * @endcode
  *
- * Wire Format (region absent, 17 bits):
- * | Bit 0   | Bits 1-16 |
- * |---------|-----------|
- * | Opt=0   | id(16)    |
+ * @par Wire Format (region ABSENT, 17 bits):
+ * @code
+ * ┌────────────┬──────────────┐
+ * │ Bit 0      │ Bits 1-16    │
+ * ├────────────┼──────────────┤
+ * │ Opt=0      │ id (16)      │
+ * └────────────┴──────────────┘
+ * @endcode
  *
- * Wire Format (region present, 33 bits):
- * | Bit 0   | Bits 1-16  | Bits 17-32 |
- * |---------|------------|------------|
- * | Opt=1   | region(16) | id(16)     |
- *
- * @todo Update the Doxygen to indicate [in] and [out] parameters
+ * @par Wire Format (region PRESENT, 33 bits):
+ * @code
+ * ┌────────────┬──────────────┬──────────────┐
+ * │ Bit 0      │ Bits 1-16    │ Bits 17-32   │
+ * ├────────────┼──────────────┼──────────────┤
+ * │ Opt=1      │ region (16)  │ id (16)      │
+ * └────────────┴──────────────┴──────────────┘
+ * @endcode
  */
 #ifndef J2735_INTERNAL_DF_INTERSECTIONREFERENCEID_H
 #define J2735_INTERNAL_DF_INTERSECTIONREFERENCEID_H
 
 #include "J2735_internal_common.h"
 #include "J2735_internal_constants.h"
 
-/* Internal - Structure metadata */
-#define J2735_PREFIX_BITS_INTERSECTION_REFERENCE_ID                                                \
+/* ============================================================================================== */
+/*  INTERNAL: Structure Metadata                                                                  */
+/* ============================================================================================== */
+/**
+ * @internal
+ * @brief Number of prefix bits before first field (extension bit + optional preamble).
+ *
+ * Calculation: 0 ext + 1 opt = 1 bit (non-extensible, 1 OPTIONAL)
+ */
+#define J2735_INTERNAL_PREFIX_BITS_INTERSECTION_REFERENCE_ID                                       \
   (0U + J2735_INTERNAL_PREAMBLE_BITS(1U)) /* 0 ext + 1 opt = 1 bit (non-extensible, 1 OPTIONAL) */
 
-/* Internal - Root component size (for calculating where extensions start) */
+/* ============================================================================================== */
+/*  INTERNAL: Optional Field Indices                                                              */
+/*  (Bitmap position for each OPTIONAL field, 0-indexed from MSB)                                 */
+/* ============================================================================================== */
+#define J2735_INTERNAL_OPT_INTERSECTION_REFERENCE_ID_REGION 0U /* optional bitmap bit 0 */
 
-/* Internal - Optional field indices (bitmap index, not bit offset) */
-#define J2735_OPT_INTERSECTION_REFERENCE_ID_REGION 0U /* optional bitmap bit 0 */
-
-/* Internal - Widths */
-#define J2735_WIDTH_INTERSECTION_REFERENCE_ID_REGION(buf)                                          \
+/* ============================================================================================== */
+/*  INTERNAL: Dynamic Widths                                                                      */
+/*  (Returns 0 if field absent, else J2735_BW_<FieldType> or computed width)                      */
+/* ============================================================================================== */
+/**
+ * @internal
+ * @brief Dynamic width of OPTIONAL field 'region'.
+ * @param buf Pointer to the IntersectionReferenceID encoding.
+ * @return J2735_BW_ROAD_REGULATOR_ID if present, 0 otherwise.
+ */
+#define J2735_INTERNAL_WIDTH_INTERSECTION_REFERENCE_ID_REGION(buf)                                 \
   (J2735_INTERSECTION_REFERENCE_ID_HAS_REGION(buf) ? J2735_BW_ROAD_REGULATOR_ID : 0U)
 
-/* Internal - Offsets */
-#define J2735_OFF_INTERSECTION_REFERENCE_ID_REGION(buf)                                            \
-  J2735_PREFIX_BITS_INTERSECTION_REFERENCE_ID /*   1 */
-#define J2735_OFF_INTERSECTION_REFERENCE_ID_ID(buf)                                                \
-  (J2735_OFF_INTERSECTION_REFERENCE_ID_REGION(buf) +                                               \
-   J2735_WIDTH_INTERSECTION_REFERENCE_ID_REGION(buf))
+/* ============================================================================================== */
+/*  INTERNAL: Field Offsets                                                                       */
+/*  (Cumulative bit offset: prev_offset + prev_width)                                             */
+/* ============================================================================================== */
+/**
+ * @internal
+ * @brief Bit offset of field 'region' within IntersectionReferenceID.
+ */
+#define J2735_INTERNAL_OFF_INTERSECTION_REFERENCE_ID_REGION(buf)                                   \
+  J2735_INTERNAL_PREFIX_BITS_INTERSECTION_REFERENCE_ID /*   1 */
 
-/* Has-checkers */
+/**
+ * @internal
+ * @brief Bit offset of field 'id' within IntersectionReferenceID.
+ */
+#define J2735_INTERNAL_OFF_INTERSECTION_REFERENCE_ID_ID(buf)                                       \
+  (J2735_INTERNAL_OFF_INTERSECTION_REFERENCE_ID_REGION(buf) +                                      \
+   J2735_INTERNAL_WIDTH_INTERSECTION_REFERENCE_ID_REGION(buf))
+
+/* ============================================================================================== */
+/*  PUBLIC API: Has-Checkers (OPTIONAL Fields)                                                    */
+/* ============================================================================================== */
 /**
  * @brief Check if OPTIONAL field 'region' (RoadRegulatorID) is present.
  * @param buf Pointer to the IntersectionReferenceID encoding.
  * @return 1 if present, 0 otherwise.
  */
 #define J2735_INTERSECTION_REFERENCE_ID_HAS_REGION(buf)                                            \
-  J2735_INTERNAL_HAS_FIELD((buf), 0U, J2735_OPT_INTERSECTION_REFERENCE_ID_REGION)
+  J2735_INTERNAL_HAS_FIELD((buf), 0U, J2735_INTERNAL_OPT_INTERSECTION_REFERENCE_ID_REGION)
 
-/* Getters */
+/* ============================================================================================== */
+/*  PUBLIC API: Field Getters                                                                     */
+/* ============================================================================================== */
 /**
  * @brief Get 'region' (RoadRegulatorID, unsigned 16 bits).
  * @param buf Pointer to the IntersectionReferenceID encoding.
  * @return RoadRegulatorID value (uint16_t, range 0..65535).
  * @pre J2735_INTERSECTION_REFERENCE_ID_HAS_REGION(buf) must be true.
  */
 #define J2735_INTERSECTION_REFERENCE_ID_GET_REGION(buf)                                            \
-  ((uint16_t)J2735_READ_BITS((buf), J2735_OFF_INTERSECTION_REFERENCE_ID_REGION(buf),               \
+  ((uint16_t)J2735_READ_BITS((buf), J2735_INTERNAL_OFF_INTERSECTION_REFERENCE_ID_REGION(buf),      \
                              J2735_BW_ROAD_REGULATOR_ID))
+
 /**
  * @brief Get 'id' (IntersectionID, unsigned 16 bits).
  * @param buf Pointer to the IntersectionReferenceID encoding.
  * @return IntersectionID value (uint16_t, range 0..65535).
  */
 #define J2735_INTERSECTION_REFERENCE_ID_GET_ID(buf)                                                \
-  ((uint16_t)J2735_READ_BITS((buf), J2735_OFF_INTERSECTION_REFERENCE_ID_ID(buf),                   \
+  ((uint16_t)J2735_READ_BITS((buf), J2735_INTERNAL_OFF_INTERSECTION_REFERENCE_ID_ID(buf),          \
                              J2735_BW_INTERSECTION_ID))
 
-/* Inline Functions */
-
 #endif /* J2735_INTERNAL_DF_INTERSECTIONREFERENCEID_H */
@@ -21,23 +21,32 @@
  * @author Yogev Neumann
  * @brief J2735 PathPrediction Definition and Access Macros.
  *
+ * @par PathPrediction Wire Format (UPER):
+ * @code
  * PathPrediction ::= SEQUENCE {
- *     radiusOfCurve  RadiusOfCurvature,  -- 16 bits (signed, -32767..32767)
- *     confidence     Confidence,         -- 8 bits (unsigned, 0..200)
- *     ...                                -- Extensible (extension bit at position 0)
+ *     radiusOfCurve  RadiusOfCurvature,    -- 16 bits (signed, -32767..32767)
+ *     confidence     Confidence,           --  8 bits (unsigned, 0..200)
+ *     ...
  * }
+ * @endcode
  *
- * Wire Format (no extensions):
- * | Bit 0 | Bits 1-16           | Bits 17-24    |
- * |-------|---------------------|---------------|
- * | Ext=0 | radiusOfCurve (16)  | confidence(8) |
+ * @par Wire Format (no extensions, 25 bits):
+ * @code
+ * ┌─────────┬─────────────────────┬──────────────────┐
+ * │ Bit 0   │ Bits 1-16           │ Bits 17-24       │
+ * ├─────────┼─────────────────────┼──────────────────┤
+ * │ Ext=0   │ radiusOfCurve (16)  │ confidence (8)   │
+ * └─────────┴─────────────────────┴──────────────────┘
+ * @endcode
  *
- * Wire Format (with extensions):
- * | Bit 0 | Bits 1-16           | Bits 17-24    | Extension Data...
- * |-------|---------------------|---------------|------------------
- * | Ext=1 | radiusOfCurve (16)  | confidence(8) | (variable)
- *
- * @todo Update the Doxygen to indicate [in] and [out] parameters
+ * @par Wire Format (with extensions, variable):
+ * @code
+ * ┌─────────┬─────────────────────┬──────────────────┬──────────────────┐
+ * │ Bit 0   │ Bits 1-16           │ Bits 17-24       │ Bits 25+         │
+ * ├─────────┼─────────────────────┼──────────────────┼──────────────────┤
+ * │ Ext=1   │ radiusOfCurve (16)  │ confidence (8)   │ (extension data) │
+ * └─────────┴─────────────────────┴──────────────────┴──────────────────┘
+ * @endcode
  */
 #ifndef J2735_INTERNAL_DF_PATHPREDICTION_H
 #define J2735_INTERNAL_DF_PATHPREDICTION_H
@@ -46,52 +55,83 @@
 #include "J2735_internal_constants.h"
 #include "J2735_internal_inline.h"
 
-/* Internal - Structure metadata */
-#define J2735_PREFIX_BITS_PATH_PREDICTION                                                          \
+/* ============================================================================================== */
+/*  INTERNAL: Structure Metadata                                                                  */
+/* ============================================================================================== */
+/**
+ * @internal
+ * @brief Number of prefix bits before first field (extension bit + optional preamble).
+ *
+ * Calculation: 1 ext + 0 opt = 1 bit (extensible, all required)
+ */
+#define J2735_INTERNAL_PREFIX_BITS_PATH_PREDICTION                                                 \
   (1U + J2735_INTERNAL_PREAMBLE_BITS(0U)) /* 1 ext + 0 opt = 1 bit (extensible, all required) */
 
-/* Internal - Root component size (for calculating where extensions start) */
-#define J2735_ROOT_SIZE_BITS_PATH_PREDICTION                                                       \
-  (J2735_PREFIX_BITS_PATH_PREDICTION + J2735_BW_RADIUS_OF_CURVATURE +                              \
+/**
+ * @internal
+ * @brief Total size of root component in bits (prefix + all root fields).
+ *
+ * Used to locate where extension data begins when extension bit is set.
+ */
+#define J2735_INTERNAL_ROOT_SIZE_BITS_PATH_PREDICTION                                              \
+  (J2735_INTERNAL_PREFIX_BITS_PATH_PREDICTION + J2735_BW_RADIUS_OF_CURVATURE +                     \
    J2735_BW_CONFIDENCE) /* 25 bits */
 
-/* Internal - Optional field indices (bitmap index, not bit offset) */
-
-/* Internal - Widths */
+/* ============================================================================================== */
+/*  INTERNAL: Field Offsets                                                                       */
+/*  (Cumulative bit offset: prev_offset + prev_width)                                             */
+/* ============================================================================================== */
+/**
+ * @internal
+ * @brief Bit offset of field 'radiusOfCurve' within PathPrediction.
+ */
+#define J2735_INTERNAL_OFF_PATH_PREDICTION_RADIUS_OF_CURVE(buf)                                    \
+  J2735_INTERNAL_PREFIX_BITS_PATH_PREDICTION /*   1 */
 
-/* Internal - Offsets */
-#define J2735_OFF_PATH_PREDICTION_RADIUS_OF_CURVE(buf) J2735_PREFIX_BITS_PATH_PREDICTION /*   1 */
-#define J2735_OFF_PATH_PREDICTION_CONFIDENCE(buf)                                                  \
-  (J2735_OFF_PATH_PREDICTION_RADIUS_OF_CURVE(buf) + J2735_BW_RADIUS_OF_CURVATURE) /*  17 */
+/**
+ * @internal
+ * @brief Bit offset of field 'confidence' within PathPrediction.
+ */
+#define J2735_INTERNAL_OFF_PATH_PREDICTION_CONFIDENCE(buf)                                         \
+  (J2735_INTERNAL_OFF_PATH_PREDICTION_RADIUS_OF_CURVE(buf) + J2735_BW_RADIUS_OF_CURVATURE) /*  17  \
+                                                                                            */
 
-/* Has-checkers */
+/* ============================================================================================== */
+/*  PUBLIC API: Has-Extension Checker                                                             */
+/* ============================================================================================== */
 /**
  * @brief Check if PathPrediction has extension additions present.
  * @param buf Pointer to the PathPrediction encoding.
  * @return 1 if extensions are present, 0 otherwise.
  */
 #define J2735_PATH_PREDICTION_HAS_EXTENSION(buf) J2735_INTERNAL_HAS_EXTENSION(buf)
 
-/* Getters */
+/* ============================================================================================== */
+/*  PUBLIC API: Field Getters                                                                     */
+/* ============================================================================================== */
 /**
  * @brief Get 'radiusOfCurve' (RadiusOfCurvature, signed 16 bits).
  * @param buf Pointer to the PathPrediction encoding.
  * @return RadiusOfCurvature value (int16_t, range -32767..32767).
  */
 #define J2735_PATH_PREDICTION_GET_RADIUS_OF_CURVE(buf)                                             \
-  J2735_INTERNAL_SIGN_EXTEND(J2735_READ_BITS((buf),                                                \
-                                             J2735_OFF_PATH_PREDICTION_RADIUS_OF_CURVE(buf),       \
-                                             J2735_BW_RADIUS_OF_CURVATURE),                        \
-                             J2735_BW_RADIUS_OF_CURVATURE, int16_t)
+  J2735_INTERNAL_SIGN_EXTEND(                                                                      \
+      J2735_READ_BITS((buf), J2735_INTERNAL_OFF_PATH_PREDICTION_RADIUS_OF_CURVE(buf),              \
+                      J2735_BW_RADIUS_OF_CURVATURE),                                               \
+      J2735_BW_RADIUS_OF_CURVATURE, int16_t)
+
 /**
  * @brief Get 'confidence' (Confidence, unsigned 8 bits).
  * @param buf Pointer to the PathPrediction encoding.
  * @return Confidence value (uint8_t, range 0..200).
  */
 #define J2735_PATH_PREDICTION_GET_CONFIDENCE(buf)                                                  \
-  ((uint8_t)J2735_READ_BITS((buf), J2735_OFF_PATH_PREDICTION_CONFIDENCE(buf), J2735_BW_CONFIDENCE))
+  ((uint8_t)J2735_READ_BITS((buf), J2735_INTERNAL_OFF_PATH_PREDICTION_CONFIDENCE(buf),             \
+                            J2735_BW_CONFIDENCE))
 
-/* Inline Functions */
+/* ============================================================================================== */
+/*  PUBLIC API: Size Function                                                                     */
+/* ============================================================================================== */
 /**
  * @brief Calculate total size in bits of a PathPrediction encoding.
  *
@@ -106,25 +146,24 @@ static inline int j2735_inline_path_prediction_size(uint8_t const *const buf,
                                                     uint32_t *const out_size_bits) {
   int result = 0;
 
-  /* TODO: Investigate all those suppressions */
   /* cppcheck-suppress misra-c2012-11.3 ; Zero-copy architecture requires packed-struct cast */
   /* cppcheck-suppress misra-c2012-17.3 ; cppcheck false positive: v is struct member, not function
    */
   /* cppcheck-suppress misra-config ; cppcheck cannot resolve struct member v through macro
    * expansion */
   if (J2735_PATH_PREDICTION_HAS_EXTENSION(buf) == 0U) {
-    *out_size_bits = J2735_ROOT_SIZE_BITS_PATH_PREDICTION;
+    *out_size_bits = J2735_INTERNAL_ROOT_SIZE_BITS_PATH_PREDICTION;
     result = 0;
   } else {
     /* Extensions present - parse them to find total size */
     uint32_t ext_bits = 0U;
-    int const parse_result =
-        j2735_internal_inline_skip_extensions(buf, J2735_ROOT_SIZE_BITS_PATH_PREDICTION, &ext_bits);
+    int const parse_result = j2735_internal_inline_skip_extensions(
+        buf, J2735_INTERNAL_ROOT_SIZE_BITS_PATH_PREDICTION, &ext_bits);
     if (0 != parse_result) {
       *out_size_bits = 0U;
       result = parse_result;
     } else {
-      *out_size_bits = J2735_ROOT_SIZE_BITS_PATH_PREDICTION + ext_bits;
+      *out_size_bits = J2735_INTERNAL_ROOT_SIZE_BITS_PATH_PREDICTION + ext_bits;
       result = 0;
     }
   }