Skip to content

Format + @name = value method annotations; migrate the deprecated above-method form - #22

Merged
VojtechVitek merged 2 commits into
masterfrom
method-annotation-meta-lines
Oct 20, 2026
Merged

VojtechVitek merged 2 commits into
masterfrom
method-annotation-meta-lines

Conversation

@VojtechVitek

@VojtechVitek VojtechVitek commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

webrpc v0.48.0 moved method annotations below the - Method() line, and webrpc#537 settled the syntax: + @name = value with struct field tag value rules. ridlfmt now speaks that syntax and migrates the deprecated above-method form for you.

What changed

  • New + @name = value and + @success 200|201 meta-lines under methods are formatted one per line at method indent. Bare values are a single word; quoted values stay verbatim; # comments are preserved.
  • The v0.48.0 colon form (+ @auth:ApiKeyAuth), now rejected by the parser, normalizes to =. Multi-word values get quoted automatically so the output parses.
  • Deprecated above-method @annotations move below the method as + @name = value lines. Multi-annotation lines split one per line, inline comments stay attached.
  • @success keeps its route-code space form: + @success:200, + @success = 200 and + @success 200 | 201 all become + @success 200|201. Old-form @success:... above a method deliberately stays put — below a method the name is route-scoped and webrpc asks users to pick a new name themselves.
  • Values webrpc can't represent (a literal " or \ in a value that needs quoting) are left byte-unchanged so the parser can flag them, instead of emitting an "escaped" form the parser would reject anyway.
  • # inside quoted values (including after escaped quotes) is no longer mistaken for a comment.

Example

service ExampleService
  @deprecated:Pong
  @auth:ApiKeyAuth @whodsa:JWT
  - Ping()
    + GET /ping
    + @success 200

formats to:

service ExampleService
  - Ping()
    + @deprecated = Pong
    + @auth = ApiKeyAuth
    + @whodsa = JWT
    + GET /ping
    + @success 200

Test plan

  • go test ./... green, incl. colon→equals normalization, auto-quoting, escaped-quote # round-trips, @success variants, old-form migration, and format-twice idempotency.
  • Formatted corpus verified against the real webrpc parser at d78d1d0: zero warnings, idempotent re-format.
Agent spend: 💰 $4.70, 2h18m active
SPEND_TREE

🤖 This message was generated by pi using Kimi K3 on behalf of Vojtech.

…-method form

webrpc v0.48.0 moved method annotations to `+ @name[:value]` meta-lines
below the `- Method()` line and added method-level `+ @success NNN`.

- Format `+ @name[:value]` / `+ @success NNN` lines under methods, one
  annotation per line; unquoted values run to end of line.
- Move deprecated above-method `@annotations` below the method as
  `+ @annotation` lines automatically; multi-annotation lines are split,
  inline comments stay attached.
- Stop treating `#` inside quoted values (e.g. `@see:"#frag"`) as a
  comment, and split name/value on the first colon only (URLs in values).
- Normalize `@success:NNN` to the space-separated form webrpc expects.

Verified against webrpc v0.48.0: formatted output parses warning-free.

Co-Authored-By: DeepSeek v4.1 Flash <noreply@deepseek.com>
Comment thread formatter/formatter_test.go Resolved
webrpc replaced the below-method `+ @name:value` form with
`+ @name = value`, using struct field tag value rules: bare values are
a single word, anything with spaces needs quotes.

- Emit `+ @name = value`; normalize the shipped colon form to `=`.
- Auto-quote multi-word values; values with `"` or `\` that webrpc
  can't represent are left unchanged for the parser to flag.
- Keep `@success` in its route-code space form (`+ @success 200|201`),
  normalizing `:`/`=` variants and spaced pipe lists.
- Old-form `@success:...` stays above the method: below a method the
  name is route-scoped and webrpc asks users to rename it themselves.
- Track escaped quotes in findCommentIndex so `\"` inside a quoted
  value doesn't leak comment detection; raw multi-word old-form values
  are quoted on migration instead of space-stripped.

Verified against webrpc master (d78d1d0): formatted corpus parses
warning-free and formats idempotently.

Co-Authored-By: DeepSeek v4.1 Flash <noreply@deepseek.com>
@VojtechVitek VojtechVitek changed the title Format + @name[:value] method annotations; migrate the deprecated above-method form Format + @name = value method annotations; migrate the deprecated above-method form Oct 20, 2026
@VojtechVitek
VojtechVitek merged commit b9f935c into master Oct 20, 2026
1 check passed
@VojtechVitek
VojtechVitek deleted the method-annotation-meta-lines branch October 20, 2026 22:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants