Add Doxygen annotations, resolve TODOs, and minimize stale CI comments (#8)

## Pull Request

### Description

Add directional Doxygen `@param` annotations to all generated and
hand-written C headers, resolve remaining TODO comments across the
Python tooling, and auto-minimize stale CI report comments on PRs.

1. **Doxygen `@param[in]`/`@param[out]` annotations**: Updated 7 Jinja2
templates (`sequence_get`, `sequence_has_extension`,
`sequence_has_field`, `sequence_size`, `sequence_internal_off`,
`sequence_internal_width`, `bitstring_internal_get_one`) and 3
hand-written headers (`J2735_internal_common.h`,
`J2735_internal_inline.h`, `J2735_api.h`) to use directional parameter
annotations. All 15 generated DE headers and 4 generated DF headers now
emit `@param[in]`/`@param[out]` consistently.
2. **TODO resolution — `j2735.py`**: Replaced two independent
`--summary`/`--types` argparse arguments with
`add_mutually_exclusive_group()`, so conflicting flags produce a proper
error instead of silently ignoring one; removed the associated TODO.
3. **TODO resolution — `j2735_c_generator_jinja.py`**: Removed stale
`filter_c_type` TODO (6 existing doctests already cover the function);
suppressed Pylance `reportUnknownMemberType` on untyped `env.filters`
with an explicit `cast(dict[str, Any], ...)`.
4. **TODO resolution — `j2735_spec_parser.py`**: Replaced
circular-reference TODO+`pass` with a descriptive comment and explicit
`return None`; clarified 8 "Inspect if still unused" field TODOs →
"Evaluate for generated C Doxygen" to reflect their actual status.
5. **TODO resolution — `j2735_spec_constraints.py`**: Replaced
placeholder `TODO` docstring on `BitStringConstraint.ext_bits` with a
proper description.
6. **Template fix**: Removed stale `@todo` markers from
`assemble_de_bitstring.j2`; fixed non-extensible wire-format docs that
incorrectly included an extension bit in the total count.
7. **CI workflows**: Added GraphQL `minimizeComment` mutation to both
`ci.yml` and `python.yml` to auto-collapse stale report comments from
previous commits.

### Related Issue

N/A

### Additional Notes

N/A

### Type of Change

- [ ] 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/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.