manual: add gas-calculation page (#322)

Fixes #290

Author: i582

README.md

@@ -13,6 +13,7 @@ This language server/extension provides support for the [Tact programming langua
 - On-the-fly inspections with quick fixes
 - Signature help inside calls, `initOf` and struct initialization
 - [Lenses] with implementation/reference counts
+- [Gas estimates] for assembly functions
 - Building projects with Blueprint and Tact Template
 - Integration with Tact compiler and Misti static analyzer
 
@@ -24,6 +25,7 @@ This language server/extension provides support for the [Tact programming langua
 [definition]: https://github.com/tact-lang/tact-language-server/blob/master/docs/manual/features/navigation.md#go-to-definition
 [type definition]: https://github.com/tact-lang/tact-language-server/blob/master/docs/manual/features/navigation.md#go-to-type-definition
 [Lenses]: https://github.com/tact-lang/tact-language-server/blob/master/docs/manual/features/code-lenses.md
+[Gas estimates]: https://github.com/tact-lang/tact-language-server/blob/master/docs/manual/features/gas-calculation.md
 
 ## Quick start
 

docs/manual/assets/gas-calculation.png

@@ -0,0 +1,56 @@
+# Gas Calculation
+
+The Language Server provides gas consumption analysis for assembly functions.
+
+Gas consumption information is displayed in two ways:
+
+1. In the documentation when hovering over a function
+2. As inline hint after the opening bracket of the function body
+
+![Gas calculation example](../assets/gas-calculation.png)
+
+## Accuracy
+
+The accuracy of gas calculations depends on the function complexity:
+
+- **Simple functions**: Calculations are quite accurate
+- **Complex functions** (with branches and loops): Calculations are approximate
+
+## Calculation Rules
+
+The Language Server uses the following rules to estimate gas consumption:
+
+### Branching (if-else)
+
+- Take the branch with the highest gas consumption
+- This provides a "worst-case scenario" estimation
+
+### Loops
+
+- Applies to `while`, `until`, and `repeat` statements
+- Gas consumption is calculated as: `loop_body_gas * coefficient`
+- Default coefficient is 5
+- You can adjust this in VS Code settings:
+    - Open **Settings**
+    - Search for **"Tact: Editor › Gas Calculation"**
+    - Modify **"Loop Gas Coefficient"**
+
+### Unknown Instructions
+
+- Instructions without known gas costs are counted as zero gas
+- This might lead to underestimation in some cases
+
+## Tips
+
+- Use these calculations as guidelines rather than exact values
+
+## Disabling Gas Hints
+
+If you don't need gas calculations, you can disable them:
+
+1. Open VS Code **Settings**
+2. Search for **"Tact: Editor › Gas Hints"**
+3. Disable the relevant options:
+    - **"Show Gas Consumption"**: For asm functions
+    - **"Show Asm Instruction Gas"**: For individual instructions
+    - **"Show Continuation Gas"**: For continuation blocks

docs/manual/features/gas-calculation.md

@@ -18,7 +18,7 @@ import type {Node as SyntaxNode} from "web-tree-sitter"
 import {computeSeqGasConsumption, instructionPresentation} from "@server/asm/gas"
 import * as compiler from "@server/compiler/utils"
 import {FileDiff} from "@server/utils/FileDiff"
-import {InlayHintLabelPart, MarkupKind} from "vscode-languageserver"
+import {InlayHintLabelPart, MarkupContent, MarkupKind} from "vscode-languageserver"
 import {Location} from "vscode-languageclient"
 import {asLspRange} from "@server/utils/position"
 import {URI} from "vscode-uri"
@@ -124,6 +124,11 @@ export function collect(
 
     const result: InlayHint[] = []
 
+    const gasHintTooltip: MarkupContent = {
+        kind: "markdown",
+        value: "Note that this value is approximate!\n\nLearn more about how LS calculates this: https://github.com/tact-lang/tact-language-server/blob/master/docs/manual/features/gas-calculation.md",
+    }
+
     RecursiveVisitor.visit(file.rootNode, (n): boolean => {
         const type = n.type
 
@@ -352,6 +357,7 @@ export function collect(
                     line: openBrace.endPosition.row,
                     character: openBrace.endPosition.column,
                 },
+                tooltip: gasHintTooltip,
                 paddingLeft: true,
             })
         }
@@ -400,6 +406,7 @@ export function collect(
                     line: openBrace.endPosition.row,
                     character: openBrace.endPosition.column,
                 },
+                tooltip: gasHintTooltip,
             })
             return true
         }