feat(openrpc): curated description overrides for params, types, and results#145
feat(openrpc): curated description overrides for params, types, and results#145akobrin1 wants to merge 2 commits into
Conversation
…esults Adds three JSON override files under docs/openrpc/ that let humans curate JSON-RPC descriptions on top of the auto-generated `"Go type: ..."` fallbacks the openrpcgen tool produces: - param_overrides.json: per (method, param-name) descriptions; 115 entries covering every previously-ugly top-level param across debug_*, eth_*, miner_*, personal_*, txpool_*, web3_* namespaces. - type_overrides.json: per (Go type, field) descriptions applied at every struct expansion site; seeded with types.TraceConfig (11 fields) and types.ChainConfig (24 fields). Type-keying deduplicates across all methods that consume the same struct. - result_overrides.json: per-method result descriptions; 83 entries with Lumera-specific context (chain ID, no-uncles post-merge, miner_* are no-ops on CometBFT, etc.). Mechanism: each override file is loaded once at generation time and applied as the highest-precedence layer, after AST source comments and existing type-based Go overrides. Missing entries fall through to the prior behavior, so adoption is incremental. Also moves the existing examples_overrides.json into docs/openrpc/ for co-location and drops the redundant `openrpc_` filename prefix now that the directory conveys it. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The Markdown sources under docs/evm-integration/ are now the canonical reference; the standalone PDF was a stale snapshot. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0cdd51328a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| if ovr.Description != "" { | ||
| fieldSchema["description"] = ovr.Description | ||
| } | ||
| if ovr.Schema != nil { | ||
| fieldSchema = ovr.Schema | ||
| } |
There was a problem hiding this comment.
When a type_overrides.json entry specifies both description and schema, the current order sets fieldSchema["description"] and then immediately replaces fieldSchema with ovr.Schema, which drops the curated description unless it is duplicated inside schema. This makes combined overrides behave incorrectly and can silently remove intended documentation for nested fields whenever authors provide both keys in one override entry.
Useful? React with 👍 / 👎.
1 participant
Summary
Replaces auto-generated
"Go type: bool"-style descriptions indocs/openrpc.jsonwith curated, Lumera-specific descriptions sourced from human-written JSON override files.Three new override layers, all under
docs/openrpc/:param_overrides.json(method, param-name)debug_*,eth_*,miner_*,personal_*,txpool_*,web3_*.type_overrides.json(Go type, field-name)types.TraceConfig(11) +types.ChainConfig(24) = 35TraceConfig.debugis reused by all 5debug_trace*methods).result_overrides.jsonmethodchain_id = 0x494c1a9, no-uncles post-merge,miner_*are no-ops on CometBFT, etc.).Also moves the pre-existing
docs/openrpc_examples_overrides.jsonintodocs/openrpc/for co-location and drops the redundantopenrpc_filename prefix.Mechanism
Each override file is loaded once at generation time by
tools/openrpcgenand applied as the highest-precedence layer, after AST source comments and the existing in-GoparamDescriptorOverridefunction. Missing entries fall through to the prior behavior — adoption is incremental.Generator flags:
-params docs/openrpc/param_overrides.json-types docs/openrpc/type_overrides.json-results docs/openrpc/result_overrides.jsonUpdated
Makefilepasses all three by default; the Makefile inputs list also tracks the JSONs sodocs/openrpc.jsonrebuilds when overrides change.Effect
"Parameter \...`. Go type: ..."`"Go type: ...""Go type: ..."TransactionArgs,FilterCriteria,TypedData)Test plan
make openrpcregeneratesdocs/openrpc.jsonandapp/openrpc/openrpc.json.gzjqconfirms 0 top-level params and 0 results retain the"Go type: ..."defaultTraceConfig.debugreads identically indebug_traceCall,debug_traceBlockByHash,debug_traceTransaction)go test ./tools/openrpcgen/... ./app/openrpc/...passesmake lint→ 0 issues/openrpc.jsonendpoint) renders the new descriptionsFuture work
Top remaining types with auto-generated nested-field descriptions, ranked by impact:
types.TransactionArgs(18 fields, appears in 7+ methods)filters.FilterCriteria(5 fields, appears ineth_getLogsandeth_newFilter)apitypes.TypedData(4 fields, appears ineth_signTypedData)Each is one JSON entry away — no further code changes required.
🤖 Generated with Claude Code