[oschema generator] first service method after a # banner comment inherits the banner as its description (persists after #153, on `ef0b8872`) #158

New issue

Open

opened 2026-06-16 16:35:19 +00:00 by sameh-farouk · 1 comment

sameh-farouk commented

2026-06-16 16:35:19 +00:00

Member

Summary

The oschema→OpenRPC generator assigns the preceding # banner/section comment as the description of the first service-block method that follows it, overriding that method's own trailing inline comment. Cosmetic (drives only the API Docs pane / openrpc.json descriptions) — no wire/param/functional impact — but the descriptions are wrong. Distinct from #153 (off-by-one between methods, closed); this is "section-banner-comment becomes the next method's description".

Evidence (verified on hero_lib@development HEAD `ef0b8872`)

hero_collab oschema/main/90_service.oschema:

# ── system ──────────────────────────────────────────────
ping()        -> bool      # liveness check; true if the server is responsive
system_ping() -> OkResult  # legacy liveness check; { ok: true }
...
# ── message & thread ────────────────────────────────────
message_send(...) -> ...    # <real description>
message_list(...) -> ...    # channel history (paginated)

Regenerated openrpc_main.json (collab rebuilt against hero_lib ef0b8872):

ping.description = "── system ──────…" ❌ (should be "liveness check; true if the server is responsive")
message_send.description = "── message & thread ──…" ❌
system_ping.description = "legacy liveness check; { ok: true }" ✅ (trailing comment, not section-leading)
message_list.description = "channel history (paginated)" ✅

So: methods with a trailing inline comment get the correct description except the first method after a banner # comment, which inherits the banner. Bumping hero_lib from af60a537 → ef0b8872 did not fix it (re-verified by regenerating collab).

Likely cause

The parser's doc-comment accumulator treats a leading section/banner comment line as the doc for the next method instead of preferring the method's own trailing inline comment (or it should reset the accumulator on a blank line / banner line). Probably the same code path #153 touched.

Impact / urgency

Cosmetic — API Docs pane only. Every generator consumer with banner comments before service methods (hero_collab, likely hero_planner/hero_proc) shows a few wrong method descriptions until fixed + regenerated. Low urgency; flagging so it's tracked (surfaced while checking #153's regeneration requirement).

## Summary The oschema→OpenRPC generator assigns the **preceding `#` banner/section comment** as the `description` of the **first service-block method that follows it**, overriding that method's own trailing inline comment. Cosmetic (drives only the API Docs pane / `openrpc.json` descriptions) — no wire/param/functional impact — but the descriptions are wrong. Distinct from #153 (off-by-one between methods, closed); this is "section-banner-comment becomes the next method's description". ## Evidence (verified on hero_lib@development HEAD `ef0b8872`) hero_collab `oschema/main/90_service.oschema`: ``` # ── system ────────────────────────────────────────────── ping() -> bool # liveness check; true if the server is responsive system_ping() -> OkResult # legacy liveness check; { ok: true } ... # ── message & thread ──────────────────────────────────── message_send(...) -> ... # <real description> message_list(...) -> ... # channel history (paginated) ``` Regenerated `openrpc_main.json` (collab rebuilt against hero_lib `ef0b8872`): - `ping.description` = `"── system ──────…"` ❌ (should be "liveness check; true if the server is responsive") - `message_send.description` = `"── message & thread ──…"` ❌ - `system_ping.description` = `"legacy liveness check; { ok: true }"` ✅ (trailing comment, not section-leading) - `message_list.description` = `"channel history (paginated)"` ✅ So: methods with a trailing inline comment get the correct description **except** the first method after a banner `#` comment, which inherits the banner. Bumping hero_lib from `af60a537` → `ef0b8872` did **not** fix it (re-verified by regenerating collab). ## Likely cause The parser's doc-comment accumulator treats a leading section/banner comment line as the doc for the next method instead of preferring the method's own trailing inline comment (or it should reset the accumulator on a blank line / banner line). Probably the same code path #153 touched. ## Impact / urgency Cosmetic — API Docs pane only. Every generator consumer with banner comments before service methods (hero_collab, likely hero_planner/hero_proc) shows a few wrong method descriptions until fixed + regenerated. Low urgency; flagging so it's tracked (surfaced while checking #153's regeneration requirement).

sameh-farouk commented

2026-06-21 08:51:44 +00:00

Author

Member

Still reproduces on latest development HEAD dd550aa4 (re-verified by bumping hero_collab to dd550aa4 + regenerating). Despite the parser rework that landed since (parser.rs now has last_comment_line / blank-line-gap + is_header_delimiter handling via the integration→development convergence merge), the bug persists:

ping.description = "── system ──…" (should be its own trailing comment)
message_send.description = "── message & thread ──…"
system_ping / message_list (trailing-comment methods) are correct.

So whatever the new blank-line-gap logic targets, the first service method after a # ── banner ── section comment still inherits the banner. Keeping open.

**Still reproduces on latest `development` HEAD `dd550aa4`** (re-verified by bumping hero_collab to dd550aa4 + regenerating). Despite the parser rework that landed since (`parser.rs` now has `last_comment_line` / blank-line-gap + `is_header_delimiter` handling via the integration→development convergence merge), the bug persists: - `ping.description` = `"── system ──…"` (should be its own trailing comment) - `message_send.description` = `"── message & thread ──…"` - `system_ping` / `message_list` (trailing-comment methods) are correct. So whatever the new blank-line-gap logic targets, the **first service method after a `# ── banner ──` section comment still inherits the banner**. Keeping open.