fix(bind-utils): fix doxygen-rs panic on @param colon syntax

[shunsuke-shimomura]

Summary

• @param[in] name: desc や @param[in]: desc のようにコロンが含まれる doxygen コメントを bindgen で処理すると、doxygen-rs がパニックする問題を修正
• process_comment でコロンを除去する前処理 (strip_doxygen_param_colon) を追加

背景

c2a-core のヘッダー (tc_segment.h, tc_transfer_frame.h 等) には @param[in] tctf: TcTransferFrame や @param[in]: TcSegment 形式の doxygen コメントが存在する。これらのヘッダーを bindgen で処理すると、doxygen-rs (0.4.2) が以下のエラーでパニックする:

failed to transform the comments: UnexpectedInput { found: "in]:", expected: ["in]", "out]"] }

Doxygen 本体はこの形式を許容するが、doxygen-rs のパーサーはより厳密でコロンを受け付けない。

対応内容

strip_doxygen_param_colon 関数を追加し、以下の 2 パターンを処理:

1. @param[in]: desc → @param[in] desc (パラメータ名なし)
2. @param[in] name: desc → @param[in] name desc (パラメータ名あり)

既存の @retval { → @retval return_value { の前処理と同じアプローチ。

Test plan

• c2a-mobc-geox (packet-codec crate) で tc_transfer_frame.h を include した状態で cargo build が成功することを確認

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR prevents doxygen-rs (via bindgen’s process_comment) from panicking on Doxygen @param lines that include a colon immediately after the direction specifier or parameter name (e.g. @param[in]: desc, @param[in] name: desc) by normalizing those lines before passing them to doxygen_rs::transform.

Changes:

• Add a preprocessing step in process_comment to strip problematic colons from @param lines.
• Introduce strip_doxygen_param_colon to handle both “no parameter name” and “parameter name with trailing colon” forms.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[shunsuke-shimomura]

check_encodingが落ちてるのは既存のファイルっぽい

[sksat (sksat)]

shunsuke-shimomura レビューしました 🙏 修正自体は正しくマルチバイトセーフですが、2 点ご相談です（doxygen-rs 0.4.2 に対して実際に挙動を検証しました）。

🔴 名前付き形式 @param[in] name: はパニックしない

両形式を doxygen_rs::transform に直接通すと:

入力	結果
@param[in]: TcSegment（名前なし）	PANIC
@param[in] tctf: TcTransferFrame（名前あり）	OK → `tctf:` (direction in) - TcTransferFrame

実際にパニックするのは 名前なし の @param[in]: だけでした。名前付き形式は問題なくパースされ、コロンを名前に含めてレンダリングするだけです。引用されているエラー（found: "in]:"）自体が名前なしケースのものです。

つまり、

• PR 説明の「@param[in] name: desc でもパニックする」は事実と異なります。
• バイト演算の複雑さがすべて詰まっているケース2（名前付き）はパニック修正には不要で、純粋に見た目の改善（`tctf:` → `tctf`）です。しかも名前付き形式はヘッダー全体で 400 箇所以上あり、生成 doc を大量に変更します。

ヘッダーの direction は 3 種類のみ（[in] ×433 / [in,out] ×73 / [out] ×38）なので、パニック修正は既存の @retval { と同じスタイルで ~3 行に収まります:

let comment = comment
    .replace("@param[in]:", "@param[in]")
    .replace("@param[out]:", "@param[out]")
    .replace("@param[in,out]:", "@param[in,out]");

ご相談（どちらか）:

• (a) strip_doxygen_param_colon を削除して上記 3 行に。明らかに正しく、新たなリスク面なし（個人的にはこちら推し）。
• (b) 見た目のクリーンアップを残すなら、PR 説明の修正＋ユニットテスト追加をお願いします。

🟡 ユニットテストがない

手作業のバイトインデックス演算なのにテストが無く、テストプランは「下流で build が通る」だけです。手元で移植して全ケース正しい（a:b ratio の説明内コロンを残す点・日本語非破壊も）ことは確認済みですが、(b) を選ぶならリポジトリ内にテストが欲しいです。

🟢 nit

!result.is_empty() を「先頭行ではない」の代用にしているため先頭の空行が落ちます。後段の transform が trim するので無害ですが、ループを残すなら lines().enumerate() 等の方が綺麗です。

---

なお check_encoding CI が赤いのは chardet 7.x の無関係な要因で、main では既に直っているので rebase すれば解消します 🙏

[sksat (sksat)]

Claude すぎる review comment が投稿されたな