feat: tolk-functions-methods #1699
Conversation
|
/review |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| ### Receiver and `self` | ||
|
|
||
| The type of `self` is determined by the receiver. All parameters after `self` must have explicit types. If the return type is omitted, it is inferred. | ||
|
|
||
| ```tolk | ||
| fun Point.equalTo(self, r: Point) { // auto-infer `bool` | ||
| return self.x == r.x && self.y == r.y | ||
| } | ||
| ``` | ||
|
|
||
| ### Methods for non-struct types | ||
|
|
||
| Methods are not limited to structures. They may be declared for any receiver type, unions, aliases, and primitives: | ||
|
|
||
| ```tolk | ||
| fun int.one() { | ||
| return 1 | ||
| } | ||
| fun int.negate(self) { | ||
| return -self | ||
| } | ||
| fun demo() { | ||
| return int.one().negate() // -1 | ||
| } | ||
| ``` | ||
|
|
||
| All standard methods are declared this way: `fun cell.hash(self)`, etc. | ||
|
|
||
| The type of `self` is determined by the receiver. | ||
| All parameters after should have their types set. | ||
| The return type is inferred if omitted. | ||
| All standard methods are declared this way: `fun cell.hash(self)`. | ||
|
|
||
| ```tolk | ||
| fun Point.equalTo(self, r: Point) { // auto-infer `bool` | ||
| return self.x == r.x && self.y == r.y | ||
| } | ||
| ``` | ||
| ## Immutability of `self` | ||
|
|
||
| ## `self` is immutable by default | ||
| In instance methods, `self` is immutable by default. | ||
|
|
||
| To allow modifications, declare `mutate self` explicitly. | ||
| For details, see [mutability](/languages/tolk/syntax/mutability). | ||
| To allow modifications, declare [`mutate self`](/languages/tolk/syntax/mutability) explicitly. | ||
|
|
||
| ```tolk | ||
| // mind `mutate` — to allow modifications | ||
| fun Point.reset(mutate self) { | ||
| self.x = 0; | ||
| self.y = 0; | ||
| } | ||
| ``` | ||
|
|
||
| ## `return self` makes a chainable method | ||
| ### Returning `self` and method chaining | ||
|
|
||
| Returning `self` makes a method chainable. To enable chaining, declare the `return` type as `self`. |
There was a problem hiding this comment.
[HIGH] Code font used in headings
The section headings “Receiver and self”, “Immutability of self”, and “Returning self and method chaining” still contain inline code formatting on self in the heading text. The internal style guide requires headings to avoid styling such as code font or quotes (outside narrow reference-page exceptions) to keep the table of contents consistent and easily scannable. Leaving self styled in headings makes the TOC visually noisy and inconsistent with other documentation. The code font can remain in the body text while the headings themselves use plain text, in line with Style rule — headings formatting.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
| ## Function declaration | ||
|
|
||
| - `fun f(<params>)` — a function | ||
| - `fun <receiver>.f(<params>)` — a method: | ||
| - `fun <receiver>.f(self, ...)` — an instance method | ||
| - `fun <receiver>.f(...)` — a static method (no `self`) | ||
| A function is declared using the `fun` keyword, followed by the function name and parameters: | ||
|
|
||
| All features are identical except for the receiver. | ||
| Most examples below use functions, but all concepts equally apply to methods. | ||
| ```tolk | ||
| fun f(<params>) | ||
| ``` | ||
|
|
||
| ### Parameter type | ||
|
|
||
| ## Types for parameters are required | ||
| Each function parameter must have an explicit type. | ||
|
|
||
| ```tolk | ||
| // invalid: |
There was a problem hiding this comment.
[HIGH] Placeholders not defined on first use in examples
The initial function declaration example introduces the placeholder <params> in fun f(<params>) without an accompanying definition explaining what <params> represents. Shortly below, the method declaration example uses <receiver> in fun <receiver>.f(<params>), and later the attributes list introduces <number> and <anything> in @method_id(<number>) and @custom(<anything>) without first defining them. The style guide requires that placeholders written in <ANGLE_CASE> notation be explicitly defined on first use so examples are unambiguous and safe to copy into real code. Without these definitions, readers must infer the meaning of each placeholder, which reduces clarity and can lead to misinterpretation of the examples, contrary to Style rule — placeholders in examples.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
closes #1619