Conversation
laviniat1996
added
the
scope: api
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| - **TonLib types** (e.g. `raw.fullAccountState`, `tvm.cell`) come from the [TonLib TL schema](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl), the type definition language used by the C++ library powering this API. | ||
| - **Extended types** (prefixed with `ext.`) are added by TON Center to provide parsed, developer-friendly representations not available in the base TonLib schema. |
There was a problem hiding this comment.
[HIGH] Non-permalink TL schema reference and marketing-style language
The overview bullet links to the TonLib TL schema using the moving master branch (https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl) on a normative reference page. The style guide’s stable permalink rule requires versioned or permanent URLs for normative code references and forbids moving targets like master or main when a versioned URL exists. The adjacent bullet also describes extended types as “developer-friendly representations”, which is a subjective, marketing-style adjective banned by the style guide in technical sections. Together, these issues reduce reproducibility and undermine the neutral, factual tone expected for reference documentation.
| - **TonLib types** (e.g. `raw.fullAccountState`, `tvm.cell`) come from the [TonLib TL schema](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl), the type definition language used by the C++ library powering this API. | |
| - **Extended types** (prefixed with `ext.`) are added by TON Center to provide parsed, developer-friendly representations not available in the base TonLib schema. |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
This comment has been minimized.
This comment has been minimized.
|
To fix the formatting issues:
Alternatively, a maintainer can comment /fmt in this PR to auto-apply fixes in a new commit from the bot. |
|
/review |
| ## Overview | ||
|
|
||
| Every object returned by API v2 includes a `@type` field that identifies the object's structure. These values originate from two sources: |
There was a problem hiding this comment.
[HIGH] Reference heading starts at H2 instead of H3
This reference page’s first in-body heading is ## Overview, which renders as an H2 directly under the template-provided H1 from frontmatter. For reference-type pages, section content under the site-managed H1 should not introduce an additional umbrella “Overview” heading at the same level, as this creates a redundant top-level section and flattens the hierarchy. Keeping the first visible section as a descriptive H3 beneath the implicit H1 improves document structure, navigation, and adherence to the site’s heading-level rules (see https://github.com/ton-org/docs/blob/main/contribute/style-guide-extended.mdx?plain=1#L254-L272).
| ## Overview | |
| Every object returned by API v2 includes a `@type` field that identifies the object's structure. These values originate from two sources: | |
| ### Type discriminator field | |
| Every object returned by API v2 includes a `@type` field that identifies the object's structure. These values originate from two sources: |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
|
|
||
| Every object returned by API v2 includes a `@type` field that identifies the object's structure. These values originate from two sources: | ||
|
|
||
| 1. Tonlib types such as `raw.fullAccountState` and `tvm.cell`, come from the [tonlib TL schema](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl), the type definition language used by the C++ library powering this API. |
There was a problem hiding this comment.
[HIGH] Non-versioned GitHub link for normative TL schema
The link to the tonlib TL schema on line 9 points at the moving master branch on GitHub while serving as a normative reference for type identifiers. The style guide’s external reference rules require a versioned or permanent URL for precision‑critical references and forbid linking to moving targets like main, HEAD, or master when a versioned URL exists (see contribute/style-guide-extended.mdx:783-793). If the schema changes on master, this documentation could silently drift away from the behavior it describes, confusing readers and invalidating examples. Pinning the link to a specific commit preserves the intended meaning over time.
| 1. Tonlib types such as `raw.fullAccountState` and `tvm.cell`, come from the [tonlib TL schema](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl), the type definition language used by the C++ library powering this API. | |
| 1. Tonlib types such as `raw.fullAccountState` and `tvm.cell`, come from the [tonlib TL schema](https://github.com/ton-blockchain/ton/blob/<COMMIT_SHA>/tl/generate/scheme/tonlib_api.tl), the type definition language used by the C++ library powering this API. |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
| ``` | ||
| msg.dataRaw body:bytes init_state:bytes = msg.Data; | ||
| msg.dataText text:bytes = msg.Data; | ||
| msg.dataDecryptedText text:bytes = msg.Data; | ||
| msg.dataEncryptedText text:bytes = msg.Data; | ||
| ``` |
There was a problem hiding this comment.
[HIGH] Fenced code block missing language identifier
The msg.data* TL snippet at lines 181–186 is a bare fenced code block (```) without a language identifier. The style guide explicitly requires every fenced block to specify a language (see contribute/style-guide-extended.mdx:563-570) so that syntax highlighting and tooling work correctly. Leaving the language unspecified makes this example harder to read and reduces editor and documentation tooling support. Marking the block as tl keeps it consistent with other TL examples and satisfies the mandatory rule.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
3 participants
closes #1870
Add a new page with details about tonlib types.
TonLib types are the low level data structures defined by TON’s core client library (TonLib) that describe how blockchain entities like accounts, transactions, messages, and cells are represented and transmitted.