Add Doxygen annotations, resolve TODOs, and minimize stale CI comments

.github/workflows/ci.yml

@@ -460,6 +460,25 @@ jobs:
 
             const existing = comments.data.find(c => c.body.includes(marker));
 
+            // Minimize stale report comments from previous commits
+            const prefix = '<!-- j2735-ci-report-';
+            const stale = comments.data.filter(c =>
+              c.body.includes(prefix) && !c.body.includes(marker)
+            );
+            for (const old of stale) {
+              try {
+                await github.graphql(`
+                  mutation($id: ID!) {
+                    minimizeComment(input: {subjectId: $id, classifier: OUTDATED}) {
+                      minimizedComment { isMinimized }
+                    }
+                  }
+                `, { id: old.node_id });
+              } catch (error) {
+                console.warn(`Failed to minimize stale comment ${old.id}:`, error);
+              }
+            }
+
             if (existing) {
               await github.rest.issues.updateComment({
                 owner: context.repo.owner,

.github/workflows/python.yml

@@ -509,6 +509,25 @@ jobs:
 
             const existing = comments.data.find(c => c.body.includes(marker));
 
+            // Minimize stale report comments from previous commits
+            const prefix = '<!-- j2735-python-ci-report-';
+            const stale = comments.data.filter(c =>
+              c.body.includes(prefix) && !c.body.includes(marker)
+            );
+            for (const old of stale) {
+              try {
+                await github.graphql(`
+                  mutation($id: ID!) {
+                    minimizeComment(input: {subjectId: $id, classifier: OUTDATED}) {
+                      minimizedComment { isMinimized }
+                    }
+                  }
+                `, { id: old.node_id });
+              } catch (error) {
+                console.warn(`Failed to minimize stale comment ${old.id}: ${error}`);
+              }
+            }
+
             if (existing) {
               await github.rest.issues.updateComment({
                 owner: context.repo.owner,

src/J2735_api.h

@@ -19,7 +19,8 @@
 /**
  * @file
  * @author Yogev Neumann
- * @brief TODO
+ * @brief J2735 UPER parsing toolkit - public API aggregating all type definitions and access
+ * macros.
  */
 #ifndef J2735_API_H
 #define J2735_API_H

src/J2735_internal_DE_AllowedManeuvers.h

@@ -53,8 +53,6 @@
  *
  * 12-bit read layout (left-justified from bit 0):
  *   [F0..F11] (12 flag bits, no extension marker)
- *
- * @todo Update the Doxygen to indicate [in] and [out] parameters
  */
 #ifndef J2735_INTERNAL_DE_ALLOWEDMANEUVERS_H
 #define J2735_INTERNAL_DE_ALLOWEDMANEUVERS_H
@@ -144,7 +142,8 @@
  * @internal
  * @brief Extract a single flag bit from pre-read 12-bit raw value.
  *
- * @param[in] raw12   Value previously returned by J2735_INTERNAL_RAW_READ_ALLOWED_MANEUVERS().
+ * @param[in] raw12   Value previously returned by
+ *                    J2735_INTERNAL_RAW_READ_ALLOWED_MANEUVERS().
  * @param[in] bit_pos ASN.1 bit position (0-11). Use J2735_INTERNAL_BIT_ALLOWED_MANEUVERS_*
  *                    constants.
  * @return 0 or 1 as uint8_t.

src/J2735_internal_DE_BrakeAppliedStatus.h

@@ -46,8 +46,6 @@
  *
  * 5-bit read layout (left-justified from bit 0):
  *   [F0..F4] (5 flag bits, no extension marker)
- *
- * @todo Update the Doxygen to indicate [in] and [out] parameters
  */
 #ifndef J2735_INTERNAL_DE_BRAKEAPPLIEDSTATUS_H
 #define J2735_INTERNAL_DE_BRAKEAPPLIEDSTATUS_H
@@ -130,7 +128,8 @@
  * @internal
  * @brief Extract a single flag bit from pre-read 5-bit raw value.
  *
- * @param[in] raw5   Value previously returned by J2735_INTERNAL_RAW_READ_BRAKE_APPLIED_STATUS().
+ * @param[in] raw5    Value previously returned by
+ *                    J2735_INTERNAL_RAW_READ_BRAKE_APPLIED_STATUS().
  * @param[in] bit_pos ASN.1 bit position (0-4). Use J2735_INTERNAL_BIT_BRAKE_APPLIED_STATUS_*
  *                    constants.
  * @return 0 or 1 as uint8_t.

src/J2735_internal_DE_ExteriorLights.h

@@ -61,8 +61,6 @@
  *                  bit16  15..7     6..0
  *   Extended:     [Ext=1][nsnnwn:7][F0..F8]
  *                  bit16  15..9    8..0
- *
- * @todo Update the Doxygen to indicate [in] and [out] parameters
  */
 #ifndef J2735_INTERNAL_DE_EXTERIORLIGHTS_H
 #define J2735_INTERNAL_DE_EXTERIORLIGHTS_H
@@ -205,7 +203,8 @@ _Static_assert(J2735_INTERNAL_MAX_WIRE_BITS_EXTERIOR_LIGHTS ==
  *   F0 at bit 8, F1 at bit 7, ..., F8 at bit 0
  *   Formula: (raw17 >> (8 - bit_pos)) & 1
  *
- * @param[in] raw17   Value previously returned by J2735_INTERNAL_RAW_READ_EXTERIOR_LIGHTS().
+ * @param[in] raw17   Value previously returned by
+ *                    J2735_INTERNAL_RAW_READ_EXTERIOR_LIGHTS().
  * @param[in] bit_pos ASN.1 bit position (0-8). Use J2735_INTERNAL_BIT_EXTERIOR_LIGHTS_*
  *                    constants.
  * @return 0 or 1 as uint8_t.

src/J2735_internal_DE_GNSSstatus.h

@@ -49,8 +49,6 @@
  *
  * 8-bit read layout (left-justified from bit 0):
  *   [F0..F7] (8 flag bits, no extension marker)
- *
- * @todo Update the Doxygen to indicate [in] and [out] parameters
  */
 #ifndef J2735_INTERNAL_DE_GNSSSTATUS_H
 #define J2735_INTERNAL_DE_GNSSSTATUS_H
@@ -136,7 +134,8 @@
  * @internal
  * @brief Extract a single flag bit from pre-read 8-bit raw value.
  *
- * @param[in] raw8   Value previously returned by J2735_INTERNAL_RAW_READ_GNSS_STATUS().
+ * @param[in] raw8    Value previously returned by
+ *                    J2735_INTERNAL_RAW_READ_GNSS_STATUS().
  * @param[in] bit_pos ASN.1 bit position (0-7). Use J2735_INTERNAL_BIT_GNSS_STATUS_*
  *                    constants.
  * @return 0 or 1 as uint8_t.

src/J2735_internal_DE_LaneDirection.h

@@ -43,8 +43,6 @@
  *
  * 2-bit read layout (left-justified from bit 0):
  *   [F0..F1] (2 flag bits, no extension marker)
- *
- * @todo Update the Doxygen to indicate [in] and [out] parameters
  */
 #ifndef J2735_INTERNAL_DE_LANEDIRECTION_H
 #define J2735_INTERNAL_DE_LANEDIRECTION_H
@@ -124,7 +122,8 @@
  * @internal
  * @brief Extract a single flag bit from pre-read 2-bit raw value.
  *
- * @param[in] raw2   Value previously returned by J2735_INTERNAL_RAW_READ_LANE_DIRECTION().
+ * @param[in] raw2    Value previously returned by
+ *                    J2735_INTERNAL_RAW_READ_LANE_DIRECTION().
  * @param[in] bit_pos ASN.1 bit position (0-1). Use J2735_INTERNAL_BIT_LANE_DIRECTION_*
  *                    constants.
  * @return 0 or 1 as uint8_t.

src/J2735_internal_DE_LaneSharing.h

@@ -51,8 +51,6 @@
  *
  * 10-bit read layout (left-justified from bit 0):
  *   [F0..F9] (10 flag bits, no extension marker)
- *
- * @todo Update the Doxygen to indicate [in] and [out] parameters
  */
 #ifndef J2735_INTERNAL_DE_LANESHARING_H
 #define J2735_INTERNAL_DE_LANESHARING_H
@@ -140,7 +138,8 @@
  * @internal
  * @brief Extract a single flag bit from pre-read 10-bit raw value.
  *
- * @param[in] raw10   Value previously returned by J2735_INTERNAL_RAW_READ_LANE_SHARING().
+ * @param[in] raw10   Value previously returned by
+ *                    J2735_INTERNAL_RAW_READ_LANE_SHARING().
  * @param[in] bit_pos ASN.1 bit position (0-9). Use J2735_INTERNAL_BIT_LANE_SHARING_*
  *                    constants.
  * @return 0 or 1 as uint8_t.

src/J2735_internal_DE_PersonalAssistive.h

@@ -58,8 +58,6 @@
  *                  bit13  12..7     6..0
  *   Extended:     [Ext=1][nsnnwn:7][F0..F5]
  *                  bit13  12..6    5..0
- *
- * @todo Update the Doxygen to indicate [in] and [out] parameters
  */
 #ifndef J2735_INTERNAL_DE_PERSONALASSISTIVE_H
 #define J2735_INTERNAL_DE_PERSONALASSISTIVE_H
@@ -199,7 +197,8 @@ _Static_assert(J2735_INTERNAL_MAX_WIRE_BITS_PERSONAL_ASSISTIVE ==
  *   F0 at bit 5, F1 at bit 4, ..., F5 at bit 0
  *   Formula: (raw14 >> (5 - bit_pos)) & 1
  *
- * @param[in] raw14   Value previously returned by J2735_INTERNAL_RAW_READ_PERSONAL_ASSISTIVE().
+ * @param[in] raw14   Value previously returned by
+ *                    J2735_INTERNAL_RAW_READ_PERSONAL_ASSISTIVE().
  * @param[in] bit_pos ASN.1 bit position (0-5). Use J2735_INTERNAL_BIT_PERSONAL_ASSISTIVE_*
  *                    constants.
  * @return 0 or 1 as uint8_t.

src/J2735_internal_DE_PersonalDeviceUsageState.h

@@ -61,8 +61,6 @@
  *                  bit16  15..7     6..0
  *   Extended:     [Ext=1][nsnnwn:7][F0..F8]
  *                  bit16  15..9    8..0
- *
- * @todo Update the Doxygen to indicate [in] and [out] parameters
  */
 #ifndef J2735_INTERNAL_DE_PERSONALDEVICEUSAGESTATE_H
 #define J2735_INTERNAL_DE_PERSONALDEVICEUSAGESTATE_H
@@ -211,7 +209,7 @@ _Static_assert(J2735_INTERNAL_MAX_WIRE_BITS_PERSONAL_DEVICE_USAGE_STATE ==
  *   Formula: (raw17 >> (8 - bit_pos)) & 1
  *
  * @param[in] raw17   Value previously returned by
- * J2735_INTERNAL_RAW_READ_PERSONAL_DEVICE_USAGE_STATE().
+ *                    J2735_INTERNAL_RAW_READ_PERSONAL_DEVICE_USAGE_STATE().
  * @param[in] bit_pos ASN.1 bit position (0-8). Use J2735_INTERNAL_BIT_PERSONAL_DEVICE_USAGE_STATE_*
  *                    constants.
  * @return 0 or 1 as uint8_t.

src/J2735_internal_DE_PublicSafetyAndRoadWorkerActivity.h

@@ -58,8 +58,6 @@
  *                  bit13  12..7     6..0
  *   Extended:     [Ext=1][nsnnwn:7][F0..F5]
  *                  bit13  12..6    5..0
- *
- * @todo Update the Doxygen to indicate [in] and [out] parameters
  */
 #ifndef J2735_INTERNAL_DE_PUBLICSAFETYANDROADWORKERACTIVITY_H
 #define J2735_INTERNAL_DE_PUBLICSAFETYANDROADWORKERACTIVITY_H
@@ -210,7 +208,7 @@ _Static_assert(J2735_INTERNAL_MAX_WIRE_BITS_PUBLIC_SAFETY_AND_ROAD_WORKER_ACTIVI
  *   Formula: (raw14 >> (5 - bit_pos)) & 1
  *
  * @param[in] raw14   Value previously returned by
- * J2735_INTERNAL_RAW_READ_PUBLIC_SAFETY_AND_ROAD_WORKER_ACTIVITY().
+ *                    J2735_INTERNAL_RAW_READ_PUBLIC_SAFETY_AND_ROAD_WORKER_ACTIVITY().
  * @param[in] bit_pos ASN.1 bit position (0-5). Use
  * J2735_INTERNAL_BIT_PUBLIC_SAFETY_AND_ROAD_WORKER_ACTIVITY_* constants.
  * @return 0 or 1 as uint8_t.

src/J2735_internal_DE_PublicSafetyDirectingTrafficSubType.h

@@ -59,8 +59,6 @@
  *                  bit14  13..7     6..0
  *   Extended:     [Ext=1][nsnnwn:7][F0..F6]
  *                  bit14  13..7    6..0
- *
- * @todo Update the Doxygen to indicate [in] and [out] parameters
  */
 #ifndef J2735_INTERNAL_DE_PUBLICSAFETYDIRECTINGTRAFFICSUBTYPE_H
 #define J2735_INTERNAL_DE_PUBLICSAFETYDIRECTINGTRAFFICSUBTYPE_H
@@ -215,7 +213,7 @@ _Static_assert(J2735_INTERNAL_MAX_WIRE_BITS_PUBLIC_SAFETY_DIRECTING_TRAFFIC_SUB_
  *   Formula: (raw15 >> (6 - bit_pos)) & 1
  *
  * @param[in] raw15   Value previously returned by
- * J2735_INTERNAL_RAW_READ_PUBLIC_SAFETY_DIRECTING_TRAFFIC_SUB_TYPE().
+ *                    J2735_INTERNAL_RAW_READ_PUBLIC_SAFETY_DIRECTING_TRAFFIC_SUB_TYPE().
  * @param[in] bit_pos ASN.1 bit position (0-6). Use
  * J2735_INTERNAL_BIT_PUBLIC_SAFETY_DIRECTING_TRAFFIC_SUB_TYPE_* constants.
  * @return 0 or 1 as uint8_t.

src/J2735_internal_DE_TrafficLightOperationStatus.h

@@ -60,8 +60,6 @@
  *                  bit15  14..7     6..0
  *   Extended:     [Ext=1][nsnnwn:7][F0..F7]
  *                  bit15  14..8    7..0
- *
- * @todo Update the Doxygen to indicate [in] and [out] parameters
  */
 #ifndef J2735_INTERNAL_DE_TRAFFICLIGHTOPERATIONSTATUS_H
 #define J2735_INTERNAL_DE_TRAFFICLIGHTOPERATIONSTATUS_H
@@ -209,7 +207,7 @@ _Static_assert(J2735_INTERNAL_MAX_WIRE_BITS_TRAFFIC_LIGHT_OPERATION_STATUS ==
  *   Formula: (raw16 >> (7 - bit_pos)) & 1
  *
  * @param[in] raw16   Value previously returned by
- * J2735_INTERNAL_RAW_READ_TRAFFIC_LIGHT_OPERATION_STATUS().
+ *                    J2735_INTERNAL_RAW_READ_TRAFFIC_LIGHT_OPERATION_STATUS().
  * @param[in] bit_pos ASN.1 bit position (0-7). Use
  * J2735_INTERNAL_BIT_TRAFFIC_LIGHT_OPERATION_STATUS_* constants.
  * @return 0 or 1 as uint8_t.

src/J2735_internal_DE_TransitStatus.h

@@ -47,8 +47,6 @@
  *
  * 6-bit read layout (left-justified from bit 0):
  *   [F0..F5] (6 flag bits, no extension marker)
- *
- * @todo Update the Doxygen to indicate [in] and [out] parameters
  */
 #ifndef J2735_INTERNAL_DE_TRANSITSTATUS_H
 #define J2735_INTERNAL_DE_TRANSITSTATUS_H
@@ -132,7 +130,8 @@
  * @internal
  * @brief Extract a single flag bit from pre-read 6-bit raw value.
  *
- * @param[in] raw6   Value previously returned by J2735_INTERNAL_RAW_READ_TRANSIT_STATUS().
+ * @param[in] raw6    Value previously returned by
+ *                    J2735_INTERNAL_RAW_READ_TRANSIT_STATUS().
  * @param[in] bit_pos ASN.1 bit position (0-5). Use J2735_INTERNAL_BIT_TRANSIT_STATUS_*
  *                    constants.
  * @return 0 or 1 as uint8_t.

src/J2735_internal_DE_UserSizeAndBehaviour.h

@@ -57,8 +57,6 @@
  *                  bit12  11..7     6..0
  *   Extended:     [Ext=1][nsnnwn:7][F0..F4]
  *                  bit12  11..5    4..0
- *
- * @todo Update the Doxygen to indicate [in] and [out] parameters
  */
 #ifndef J2735_INTERNAL_DE_USERSIZEANDBEHAVIOUR_H
 #define J2735_INTERNAL_DE_USERSIZEANDBEHAVIOUR_H
@@ -199,7 +197,7 @@ _Static_assert(J2735_INTERNAL_MAX_WIRE_BITS_USER_SIZE_AND_BEHAVIOUR ==
  *   Formula: (raw13 >> (4 - bit_pos)) & 1
  *
  * @param[in] raw13   Value previously returned by
- * J2735_INTERNAL_RAW_READ_USER_SIZE_AND_BEHAVIOUR().
+ *                    J2735_INTERNAL_RAW_READ_USER_SIZE_AND_BEHAVIOUR().
  * @param[in] bit_pos ASN.1 bit position (0-4). Use J2735_INTERNAL_BIT_USER_SIZE_AND_BEHAVIOUR_*
  *                    constants.
  * @return 0 or 1 as uint8_t.

src/J2735_internal_DE_VehicleEventFlags.h

@@ -66,8 +66,6 @@
  *                  bit21  20..8     7..0
  *   Extended:     [Ext=1][nsnnwn:7][F0..F13]
  *                  bit21  20..14    13..0
- *
- * @todo Update the Doxygen to indicate [in] and [out] parameters
  */
 #ifndef J2735_INTERNAL_DE_VEHICLEEVENTFLAGS_H
 #define J2735_INTERNAL_DE_VEHICLEEVENTFLAGS_H
@@ -215,7 +213,8 @@ _Static_assert(J2735_INTERNAL_MAX_WIRE_BITS_VEHICLE_EVENT_FLAGS ==
  *   F0 at bit 13, F1 at bit 12, ..., F13 at bit 0
  *   Formula: (raw22 >> (13 - bit_pos)) & 1
  *
- * @param[in] raw22   Value previously returned by J2735_INTERNAL_RAW_READ_VEHICLE_EVENT_FLAGS().
+ * @param[in] raw22   Value previously returned by
+ *                    J2735_INTERNAL_RAW_READ_VEHICLE_EVENT_FLAGS().
  * @param[in] bit_pos ASN.1 bit position (0-13). Use J2735_INTERNAL_BIT_VEHICLE_EVENT_FLAGS_*
  *                    constants.
  * @return 0 or 1 as uint8_t.

src/J2735_internal_DE_VerticalAccelerationThreshold.h

@@ -46,8 +46,6 @@
  *
  * 5-bit read layout (left-justified from bit 0):
  *   [F0..F4] (5 flag bits, no extension marker)
- *
- * @todo Update the Doxygen to indicate [in] and [out] parameters
  */
 #ifndef J2735_INTERNAL_DE_VERTICALACCELERATIONTHRESHOLD_H
 #define J2735_INTERNAL_DE_VERTICALACCELERATIONTHRESHOLD_H
@@ -134,8 +132,8 @@
  * @internal
  * @brief Extract a single flag bit from pre-read 5-bit raw value.
  *
- * @param[in] raw5   Value previously returned by
- * J2735_INTERNAL_RAW_READ_VERTICAL_ACCELERATION_THRESHOLD().
+ * @param[in] raw5    Value previously returned by
+ *                    J2735_INTERNAL_RAW_READ_VERTICAL_ACCELERATION_THRESHOLD().
  * @param[in] bit_pos ASN.1 bit position (0-4). Use
  * J2735_INTERNAL_BIT_VERTICAL_ACCELERATION_THRESHOLD_* constants.
  * @return 0 or 1 as uint8_t.