Documentation for Tolk written from scratch #1421
Conversation
- all articles about Tolk type system - get rid of 'you' and 'we' in existing pages
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| For years, FunC was the primary language for TON. | ||
| It gave complete control over the TVM — and if you mastered it, it gave you power. | ||
| But its Lisp-like syntax and functional style made onboarding difficult for many. |
There was a problem hiding this comment.
[HIGH] Second-person pronoun and hype in FunC origin note
The sentence “It gave complete control over the TVM — and if you mastered it, it gave you power.” addresses the reader with “you” and uses hype-style wording (“gave you power”). This violates the guidelines against personal pronouns and marketing-style language in technical documentation. The surrounding narrative can remain factual while removing the second person and hype.
| For years, FunC was the primary language for TON. | |
| It gave complete control over the TVM — and if you mastered it, it gave you power. | |
| But its Lisp-like syntax and functional style made onboarding difficult for many. | |
| For years, FunC was the primary language for TON. | |
| It provided complete control over the TVM for developers who mastered it. | |
| But its Lisp-like syntax and functional style made onboarding difficult for many. |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
There was a problem hiding this comment.
Intentional "you", see the MR description
| obj.toCell({ | ||
| // for `bits128` and similar (a slice under the hood), | ||
| // insert the checks (bits == 128 and refs == 0); | ||
| // turn off to save gas if you guarantee input is valid; | ||
| // `intN` are always validated, it's only for `bitsN` | ||
| skipBitsNValidation: false, // default: false |
There was a problem hiding this comment.
[HIGH] Second-person pronoun in auto-serialization options comment
The inline comment “// turn off to save gas if you guarantee input is valid;” uses “you” to refer to the reader, even though this is explanatory documentation embedded in a code example. This conflicts with the style rule to avoid second-person pronouns in docs, including explanatory comments used for teaching. The meaning can be preserved by referring to conditions on the input instead.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
There was a problem hiding this comment.
Intentional "you", see the MR description
| <Aside | ||
| type="caution" | ||
| > | ||
| This page gives brief descriptions of optimizations performed. | ||
| It is fairly low-level and not required for using Tolk in production. | ||
| </Aside> |
There was a problem hiding this comment.
[HIGH] Throat-clearing “this page/section” openers
Multiple newly added Tolk pages start sections with self-referential “this page/section” sentences instead of leading directly with value, which the style guide flags as throat-clearing. In features/compiler-optimizations.mdx, the caution aside says “This page gives brief descriptions of optimizations performed. It is fairly low-level and not required for using Tolk in production.”; similar constructions appear in features/message-sending.mdx (“This section is intended for experienced users; it discusses terminology.”), syntax/operators.mdx, syntax/structures-fields.mdx, types/list-of-types.mdx, types/overall-serialization.mdx, and types/overall-tvm-stack.mdx. These meta statements add cognitive overhead without conveying new information. Rephrasing them into direct summaries of purpose, audience, or prerequisites keeps the docs concise and aligned with the style rule.
| <Aside | |
| type="caution" | |
| > | |
| This page gives brief descriptions of optimizations performed. | |
| It is fairly low-level and not required for using Tolk in production. | |
| </Aside> | |
| <Aside | |
| type="caution" | |
| > | |
| Summarizes compiler optimizations that affect gas usage. | |
| Intended as low-level background; not required for typical Tolk development. | |
| </Aside> |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
There was a problem hiding this comment.
This is not the start of the page, it's an <Aside> element after, placed specifically to attract visual attention
| If you use `RichBounce`, that's the way: | ||
|
|
||
| ```tolk | ||
| fun onBouncedMessage(in: InMessageBounced) { | ||
| val rich = lazy RichBounceBody.fromSlice(in.bouncedBody); | ||
| // handle rich.originalBody | ||
| // use rich.xxx to get exitCode, gasUsed, and so on | ||
| } | ||
| ``` |
There was a problem hiding this comment.
[HIGH] Second-person pronoun in RichBounce handling guidance
The line “If you use RichBounce, that's the way:” addresses the reader directly with “you”. This breaks the rule against using “you/your” in documentation and mixes instructional tone with informal phrasing (“that's the way”). The surrounding section already describes BounceMode variants objectively, so this sentence can be made neutral and descriptive.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
There was a problem hiding this comment.
Intentional "you", see the MR description
| - sometimes, you "send to an address" | ||
| - ... but sometimes, you have workchain + hash | ||
| - sometimes, you compose `StateInit` from code+data | ||
| - ... but sometimes, `StateInit` is a ready cell | ||
| - sometimes, you send a message to basechain | ||
| - ... but sometimes, you use a `MY_WORKCHAIN` constant | ||
| - sometimes, you just attach tons (msg value) | ||
| - ... but sometimes, you also need extra currencies |
There was a problem hiding this comment.
[HIGH] Second-person pronouns in createMessage union examples
The bullet list under “The concept is based on union types” uses multiple second-person constructions such as “sometimes, you 'send to an address'” and “sometimes, you just attach tons (msg value)”. These directly address the reader instead of describing generic behaviors, violating the no-“you/your” rule for documentation text. The list is otherwise explaining patterns of usage and can be written in neutral terms.
| - sometimes, you "send to an address" | |
| - ... but sometimes, you have workchain + hash | |
| - sometimes, you compose `StateInit` from code+data | |
| - ... but sometimes, `StateInit` is a ready cell | |
| - sometimes, you send a message to basechain | |
| - ... but sometimes, you use a `MY_WORKCHAIN` constant | |
| - sometimes, you just attach tons (msg value) | |
| - ... but sometimes, you also need extra currencies |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
There was a problem hiding this comment.
Intentional "you", see the MR description
There was a problem hiding this comment.
One more comment about "you" in these intentional places:
Even in strict docs of Rust, LLVM, Oracle, etc. it's also quite typical:
- Sometimes you need…
- Sometimes you have…
- etc.
Like here. What's important:
It does not address the reader, contains no imperatives, and avoids direct dialogue.
It is simply a description of a situation, not an interaction with the user.
| Returns `uint256` — a new pseudo-random number. | ||
|
|
||
| Ensure you've called `random.initialize` to make it unpredictable! | ||
|
|
||
| #### random.range(limit) | ||
|
|
||
| Returns `int` — a new pseudo-random integer z in the range `0..limit−1` (or `limit..−1` if negative). | ||
| More precisely, an unsigned random value `x` is generated, then `z := x * limit / 2^256` is computed. | ||
|
|
||
| Ensure you've called `random.initialize` to make it unpredictable! |
There was a problem hiding this comment.
[HIGH] Second-person pronouns in random API notes
Within the random.uint256 and random.range documentation, the line “Ensure you've called random.initialize to make it unpredictable!” appears twice. Both instances directly address the reader with “you've”, which conflicts with the style rule against second-person pronouns in documentation prose. The intent—documenting the need to initialize randomness—can be expressed in a neutral imperative form instead.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
There was a problem hiding this comment.
Intentional "you", see the MR description
| - Do you need validation or just proxy any data as-is? | ||
| - Do you need custom error codes while validating? | ||
| - Do you need to assign it dynamically or just to carry it forward? |
There was a problem hiding this comment.
[HIGH] Second-person pronouns in jetton forward-payload questions
Lines 533–535 ask the reader “Do you need …” three times, directly addressing the reader with “you”. This conflicts with the documentation style rule to avoid second-person pronouns in descriptive guidance. The surrounding section is otherwise neutral and technical, so the second-person phrasing stands out as inconsistent with the rest of the Tolk docs.
| - Do you need validation or just proxy any data as-is? | |
| - Do you need custom error codes while validating? | |
| - Do you need to assign it dynamically or just to carry it forward? |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
There was a problem hiding this comment.
Intentional "you", see the MR description
| If you are migrating from FunC: | ||
|
|
||
| int currentCounter() method_id { | ||
| load_data(); ;; fills global variables | ||
| return ctx_counter; | ||
| } | ||
| ``` | ||
| </details> | ||
| - Look through [benchmarks](https://github.com/ton-blockchain/tolk-bench): notice **30–50% lower gas fees**. | ||
| - Scan the page [Tolk vs FunC](/languages/tolk/from-func/tolk-vs-func) to get the overall picture. | ||
| - Use the [FunC-to-Tolk converter](/languages/tolk/from-func/converter) to migrate existing projects. |
There was a problem hiding this comment.
[HIGH] Second-person pronoun in FunC migration note
The line “If you are migrating from FunC:” explicitly addresses the reader with “you”. This violates the style rule banning second-person pronouns in documentation, even though the rest of the migration guidance is written neutrally. The heading line can be rephrased to describe the migration topic without addressing the reader directly.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
There was a problem hiding this comment.
Intentional "you", see the MR description
| --- | ||
|
|
||
| An article ["Type checks and casts"](/languages/tolk/types/type-checks-and-casts) |
There was a problem hiding this comment.
[HIGH] Horizontal rule in type system overview body
Line 33 contains a standalone --- after the list of type links, which renders as a horizontal rule. The style guide permits --- only as YAML frontmatter delimiters, not as thematic breaks in body content. This horizontal rule appears in the middle of the page body (not as frontmatter), so it violates the “no thematic breaks in content” rule.
| --- | |
| An article ["Type checks and casts"](/languages/tolk/types/type-checks-and-casts) | |
| An article ["Type checks and casts"](/languages/tolk/types/type-checks-and-casts) |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
There was a problem hiding this comment.
Ok, removed the <hr>
| ## `void` and `never` | ||
|
|
||
| Both represent the absence of a value and occupy zero stack slots. | ||
|
|
||
| For example, a `void` function does not place any value onto the stack. |
There was a problem hiding this comment.
[HIGH] Horizontal rule in TVM stack overview body
Near the end of overall-tvm-stack.mdx, a standalone --- line is used as a separator before the “See also” section (immediately following this range). As with the type-system overview, this is a thematic break in body content rather than YAML frontmatter. The documentation style guide disallows horizontal rules in page content, so this separator should be removed and replaced by normal spacing or headings.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
There was a problem hiding this comment.
Ok, replaced with <h2>
| ```tolk | ||
| const ONE = 1 | ||
| const MAX_AMOUNT = ton("0.05") | ||
| const ADMIN_ADDRESS = address("EQ...") |
There was a problem hiding this comment.
maybe we can add a type hint for one of the constants to show that this is possible?
There was a problem hiding this comment.
It's not "basic" syntax, it's described in the "variables" page
| - [cells](/languages/tolk/types/cells) — and also slices, builders, and raw bits | ||
| - [strings](/languages/tolk/types/strings) — not a native type, emulated using slices | ||
| - [structures](/languages/tolk/types/structures) — group several fields into one entity | ||
| - [type aliases](/languages/tolk/types/aliases) — similar to TypeScript and Rust |
There was a problem hiding this comment.
We don't require FunC knowledge, but require TypeScript and Rust knowledge here :D
There was a problem hiding this comment.
C's typedefs send their regards
| > | ||
| All these types are **257-bit integers at runtime**. | ||
| The TVM (virtual machine) has only `INT`, and all intN are actually "just integers" while running. | ||
| **Overflow happens only at serialization**. |
There was a problem hiding this comment.
Let's link with "Overflow happens only at serialization" paragraph bellow
There was a problem hiding this comment.
I don't like links inside the same page, it breaks the logic. This page should be scanned from top to bottom, as most pages do. Moreover, it's the first page in the "type system" section — probably the first page a reader enters, and it expected to read it through
| Every enum is backed by TVM INT. Serialized as `(u)intN` where `N` is: | ||
|
|
||
| - specified manually: `enum Role: int8 { ... }` | ||
| - or calculated automatically to fit all values |
There was a problem hiding this comment.
I think these two points deserve a more detailed explanation, as it can be confusing for beginners right now
| A check for `value == null` is required before: | ||
|
|
||
| ```tolk | ||
| if (value != null) { // value is `int` inside |
There was a problem hiding this comment.
A check for
value == null
if (value != null) {
maybe it's better to write: A check for value != null
| while (lastCell != null) { | ||
| lastCell = lastCell.beginParse().loadMaybeRef(); | ||
| } | ||
| // here lastCell is 100% null |
There was a problem hiding this comment.
what is 90% null? :D
// here lastCell is definitely null
| // idx is `int` | ||
| ``` | ||
|
|
||
| When a variable is 100% null, its type becomes `null`, meaning it can be safely passed to any nullable type: |
| fun doSmth(c: cell) {} | ||
| fun analyzeStorage(nCells: int, lastCell: cell?) { | ||
| if (nCells) { // then lastCell 100% not null |
| Tolk supports union types `T1 | T2 | ...` similar to TypeScript. | ||
| They allow a value to belong to one of several possible types. | ||
| Pattern matching over unions is essential for message handling. | ||
| A special case `T | null` is written as `T?` and called "nullable". |
| fun handle(m: IncomingMsg) { | ||
| match (m) { | ||
| Increment => { /* smart cast to Increment */ } |
There was a problem hiding this comment.
Not sure if smart cast term is common knowledge, maybe // here m is Increment?
| ## Operators `is` and `!is` | ||
|
|
||
| Besides `match`, unions can also be tested using `is`. | ||
| This generalizes `== null`; smart casts also apply: |
There was a problem hiding this comment.
This generalizes
== null;
I find this part confusing, it adds more questions than answers
|
|
||
| Unions have a complex stack layout, commonly named as "tagged unions". Enums in Rust work the same way. | ||
|
|
||
| Serialization depends on whether `T_i` is a structure with a manual serialization prefix: |
There was a problem hiding this comment.
... on whether
i-th type in the union is a structure with ...
| type="caution" | ||
| > | ||
| In most languages, `(v1, v2, ...)` is called a tuple. | ||
| However, in TON, a "tuple" refers to a specific TVM primitive. |
| var (i, j) = tensor; | ||
| // more complex example | ||
| var (slice, (i, j)) = ("abcd", (10, 20)); |
There was a problem hiding this comment.
"slice" is highlighted in type color here, which is confusing to readers
| ``` | ||
|
|
||
| The method `set()` does not create new elements; it only updates existing ones. | ||
| If `idx` is out of bounds in `get()` or `set()`, an exception is thrown. |
| All major IDEs support syntax highlighting and code completion: | ||
|
|
||
| The Tolk compiler itself lives in the `ton` [repository](https://github.com/ton-blockchain/ton). | ||
| 1. **JetBrains IDEs** (WebStorm, CLion, etc.) — via the [plugin](https://github.com/ton-blockchain/intellij-ton)<br /> |
There was a problem hiding this comment.
There are dedicated pages for the JetBrains plugin and VSCode/VSCodium extensions:
Marketplace links, installation steps, and features are nicely described there :)
| // modify | ||
| t.1 = 123; | ||
| t.2.storeInt(v.0, 16); |
| var m = createEmptyMap<int8, int32>(); | ||
| ``` | ||
|
|
||
| Of course, maps may be used inside structures: |
|
|
||
| ## Add values to a map | ||
|
|
||
| Use `m.set(k, v)`, `m.delete(k)`, and other suggested methods (a full list is available below): |
|
|
||
| ## How to emulate `Set<T>` with maps | ||
|
|
||
| A suggestion is to use an "empty tensor" for a map: |
|
|
||
| It will work, a bit noisy. | ||
| Lots of methods for maps are just inapplicable to sets, so its "public interface" is wrong. | ||
| Sets have a much simpler API, literally 4 functions. A canonical suggestion is something like this: |
There was a problem hiding this comment.
A canonical suggestion is something like this:
to
It's better to create a simple wrapper aroundmap<T, ()>, like this:
| // etc. | ||
| ``` | ||
|
|
||
| ## Low-level: why "isFound" but not "optional value"? |
There was a problem hiding this comment.
While this section is generally interesting, I think it's too low-level for any smart contract developer. Maybe these details deserve a separate article/chapter?
| // field `b` may be omitted | ||
| val v: WithVoid = { a: 10, c: "" }; | ||
| } | ||
| ``` |
There was a problem hiding this comment.
This example is very confusing, because why would you need to define a field that doesn't exist at all? I think we need an example with <T = void>.
|
|
||
| <TolkHighlight /> | ||
|
|
||
| **FunC** is the first language for writing smart contracts in TON. |
There was a problem hiding this comment.
FunC is the first high-level language for writing smart contracts in TON.
| TVM is a stack machine, imposing architectural and runtime restrictions. | ||
|
|
||
| Both languages **have IDE plugins**, although support for Tolk is way better. | ||
| JetBrains IDEs, VS Code, and LSP-based editors: Cursor, Windsurf, etc. |
There was a problem hiding this comment.
JetBrains IDEs, VS Code, Cursor, Windsurf, and LSP-based editors: Neovim, Zed etc.
|
|
||
| ### Tolk reminds TypeScript and Rust | ||
|
|
||
| - FunC: resembles C and Lisp ("FunC" stands for "functional C") |
There was a problem hiding this comment.
How? There is barely anything in common between Lisp and FunC, except that both have spaces, parenthesis, and their code is represented with text.
|
|
||
| ### Everything else in the type system | ||
|
|
||
| - FunC: several types, the Hindley-Milner type system |
There was a problem hiding this comment.
Type system of FunC is not Hindley-Milner.
| { | ||
| "filename": "languages/tolk/features/message-sending.mdx", | ||
| "ignoreWords": [ | ||
| "StateInit", |
There was a problem hiding this comment.
StateInit is the name of the type, not a word. We have specifically created a spellchecker rule to convert it into code.
| "filename": "languages/tolk/features/message-sending.mdx", | ||
| "ignoreWords": [ | ||
| "StateInit", | ||
| "toncoin", |
There was a problem hiding this comment.
Toncoin is the name of the currency, and must be uppercased
| { | ||
| "filename": "languages/tolk/features/compiler-optimizations.mdx", | ||
| "ignoreWords": [ | ||
| "fif", |
There was a problem hiding this comment.
If this is the extension, it's likely a part of filename that should be inside of a inline code or code block.
Can't really validate through GH interface, as this page is displayed at 1 FPS at best.
| See `snippets/tolk-highlight.jsx`. | ||
| */ | ||
|
|
||
| :root { |
There was a problem hiding this comment.
A temporary solution must have a GH issue with an assignee to fix it, and the comment should link to it.
| ``` | ||
| struct `MoneyInfo` can exceed 1023 bits in serialization (estimated size: 808..1048 bits) | ||
| ... (and some instructions) | ||
| ``` |
There was a problem hiding this comment.
We should change this to <```txt wrap> to eliminate code highlighting for the compiler message and to prevent the copy/AI buttons from obscuring the text.
There was a problem hiding this comment.
Since this is a terminal output, let's put ```ansi wrap: https://github.com/ton-org/docs/pull/1421/files/fe8dd9bb4b63e4ef4db2835e7e637b97c4b28e10#r2569352934
That way, if there were any ANSI sequences in the output, they'll be highlighted and this component won't be confused with Tolk (see the temp. highlighting component logic)
|
|
||
| And trying to serialize it, the compiler prints an error: | ||
|
|
||
| ``` |
There was a problem hiding this comment.
| ``` | |
| ```ansi wrap |
Live demo: https://companyname-a7d5b98e-tolk-docs.mintlify.app/languages/tolk/overview
I have completed a long effort to provide a from-scratch documentation for Tolk.
The previous version, which I had been incrementally maintaining since January, focused on "Tolk vs FunC" differences.
The new one does not require any prior knowledge of FunC. A reader approaches Tolk directly.
The documentation contains many examples, snippets, and real-world cases. Before starting this work, I reviewed the official docs for Rust, Go, and Kotlin — to absorb best practices for presenting a programming language.
What's inside: brief description
Every aspect of the Tolk language is covered:
Additionally, there are two entry-point pages:
The english style used while writing
All pages are written in a short, formal style (as opposed to the PR descriptions I like to create).
Syntax highlighting!
The current documentation lacks of syntax highlighing, because Mintlify does not support custom languages. FunC, Fift, etc. — all of them are rendered as black plain text.
Tolk documentation contains hundreds of snippets and looks too depressive without highlithing.
That's why I implemented a temporary solution — all snippets are now colorful, in both dark and light modes. Just take a look:
All ```tolk snippets are highlighted automatically: no changes in
mdxmarkup is required.The highlighing is client-side, via Prism.js, whose sources are embedded. See
snippets/tolk-highlight.jsx. This component is injected into every/languages/tolk/page.Hopefully, some day, Mintlify will introduce native server-side highlighing. Then, we can discuss across coloring. I fine-tuned grammar and palette the way I prefer it (for example, structures and variables have different colors, because of the capital letter). The current VS Code
tmLanguagefile is not suitable for this — it must be updated.For reviewers
If anyone decides to review all the text in this PR, keep this in mind:
...three dots in code snippets are intentional; small snippets are not meant to be copy-pasted — they demonstrate a specific featureAbout merging this PR
Git history is split into multiple sensible commits. For instance, a syntax highlighter is a separate commit.
It's up to you whether to "Squash and merge" all changes into a single commit or to "Rebase and merge" to preserve Git history. I do not see any disadvantages in having multiple commits.
For future changes
If anyone plans to modify the contents in the Tolk documentation, please remember:
The documentation in numbers
All together, the new Tolk documentation contains:
I invested ~200 hours developing the text and picking every word — exactly 14 days, about 14 hours a day.
I hope that, cumulatively, this documentation will save noticeably more time for all TON developers.
Closes #1136
Closes #1120
Closes #1114
Closes #73
Closes #1128
Live demo: https://companyname-a7d5b98e-tolk-docs.mintlify.app/languages/tolk/overview