algorand / algorand/go-algorand
Improve AVM doc generation for downstream tooling
- 主要言語
- Go
- スター
- 1.4k
- フォーク
- 537
- 平均マージ
- 1日 7時間
- マージ済み PR(30日)
- 18
説明
## Problem
The primary source of easily ingestible information for the details of AVM opcodes is the [langspec.json](https://github.com/algorand/go-algorand/blob/master/data/transactions/logic/langspec.json) file. This file is critical for higher level languages or tooling to easily update to new versions and perform better type checking.
Currently the `langspec.json` file contains a list of `OpSpec` details and some `Fields` that can be used as immediate arguments. There are a number of shortcomings of the current format if they're meant to be used by downstream tooling.
Shortcomings include:
- Lack of easily parsed immediate fields, argument name referenced in docs isn't available directly
- Difficult versioning representation (costs by version, fields available by version, first introduced)
- Lack of semantic information in an easily parsed format
- We _know_ `txn Sender` puts a 32 byte slice on the stack, we can call this `address`
- We _know_ an `==` op puts a 1/0 on the stack, we can call this `boolean`
- We _know_ the `b+` op can take, maximally, a 64 byte string, we can call this `bigint`
## Solution
1) Create a higher level type to replace the current `StackType` where we can define the bounds for the more specific type and provide a name to reference them in docs. Because this `StackType` is used in the [opdoc tool](https://github.com/algorand/go-algorand/blob/master/cmd/opdoc/opdoc.go), the smallest changes possible for that to work are also included in this change set.
2) Modify the existing Immediate documentation to provide the `Name` and `FieldGroup` if available and make the `syntax` and `bytecode` for each op more explicit.
WIP: https://github.com/algorand/go-algorand/pull/5130
3) Incorporate the changes in the above steps and produce a version of the `langspec.json` file for each version available with exactly (and only) the details available in that version.
Improve TEAL_* docs to produce a symbolic stack that is easier to read (https://github.com/algorand/go-algorand/pull/5130/files#r1150703089)
4) Add directives to docs (pragma, define)
コントリビューションガイド
評価
この issue はまだ評価されていません。