add references

.vitepress/config.ts

@@ -103,6 +103,7 @@ export default defineConfig({
           items: [
             { text: 'Immutability', link: '/memory/immutability' },
             { text: 'Pointers', link: '/memory/pointers' },
+            { text: 'References', linkd: '/memory/references' },
             { text: 'Memory Management', link: '/memory/memory-management' },
           ],
         },

src/memory/memory-management.md

@@ -3,7 +3,7 @@ Jule does the memory management itself. But it's not fully automatic. You decide
 
 Jule uses reference counting for heap allocations. It is automatically released when the reference count of the pointer reaches zero, that is, when it is certain that the heap allocation is no longer used. It is guaranteed that no allocation goes unnoticed and is also not released while the allocation is still in use.
 
-## References
+## Reference Types
 References are heap allocation data types. A reference is annotated by an `&` operator.
 
 A reference is always heap-allocation and is always within the reference counting. When a pointer to a reference is taken, you don't get a pointer to the reference. You get a pointer to the address of the heap allocation that the reference is using.
@@ -68,7 +68,7 @@ fn main() {
 ```
 
 ### Allocation Management
- References can be `nil` (aka null). This is safe, when a `nil` reference is used unsafe it will give you a panic that it is nil. When a reference is set to nil, the reference count continues to run. So when you assign to nil any reference, this reference countdown by reference count and deallocates if necessary.
+References can be `nil` (aka null). This is safe, when a `nil` reference is used unsafe it will give you a panic that it is nil. When a reference is set to nil, the reference count continues to run. So when you assign to nil any reference, this reference countdown by reference count and deallocates if necessary.
 
 Classic assignment cannot be made to assign a reference to nil. Classic assignments are always assignments to the data carried by the reference. If the data type carried by the reference is nil compatible, the nil assignment is made to the data it contains.
 

src/memory/references.md

@@ -0,0 +1,50 @@
+# References
+
+References can be confused with the reference types described in memory management, but they are completely different things. References are like an alias for an lvalue. You can think of them as pointers but they are safer.
+
+They are used with `&` operator in syntax. You can't have nested references, for example you can have a pointer pointing to a pointer but not a reference referencing to a reference.
+
+References point to the value from which they were initialized and must receive an initialize expression. The lvalue pointing to later references cannot be changed. Any assignment statement is always about changing the data they refer to.
+
+## Reference Variables
+
+Reference variables are variables that reference an lvalue. Any assignment made affects the referenced lvalue. Declared with `&` operator.
+
+For example:
+```
+fn main() {
+    let mut a = 20
+    let mut &b = a
+    b += 20
+    outln(a) // 40
+}
+```
+
+Also you can use reference types in mult-declarative assignments.
+
+For example:
+```
+fn main() {
+    let mut a = 20
+    let (mut &x, mut y) = a, 20
+    x += y
+    outln(a) // 40
+}
+```
+
+## Reference Parameters
+
+Reference parameters must take an lvalue as an argument. To specify a reference parameter, the parameter identifier must be preceded by the `&` operator.
+
+For example:
+```
+fn add_20(mut &a: int) {
+    a += 20
+}
+
+fn main() {
+    let mut a = 20
+    add_20(a)
+    outln(a) // 40
+}
+```