From 1307cfc97cdb77ef5013d7ad43ed6de714ff6a36 Mon Sep 17 00:00:00 2001
From: Alexander Medvednikov <alexander@medvednikov.com>
Date: Tue, 7 Jul 2020 11:55:22 +0200
Subject: [PATCH] doc: document array init syntax

---
 doc/docs.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/doc/docs.md b/doc/docs.md
index 2ac0a79e6e..59f97685e3 100644
--- a/doc/docs.md
+++ b/doc/docs.md
@@ -437,6 +437,27 @@ It can also append an entire array.
 
 `val in array` returns true if the array contains `val`. See [`in` operator](#in-operator).
 
+&nbsp;
+
+During initialization you can specify the capacity of the array (`cap`), its initial length (`len`),
+and the default element (`init`).
+
+Setting the capacity improves performance of insertions, as it reduces the amount of reallocations in
+dynamic arrays:
+
+```v
+numbers := []int{ cap: 1000 }
+// Now adding new elements is as efficient as setting them directly
+for i in 0 .. 1000 {
+    numbers << i
+    // same as
+    // numbers[i] = i
+}
+```
+
+`[]int{ len: 5, init: -1 }` will create `[-1, -1, -1, -1, -1]`.
+
+
 #### Array methods
 
 All arrays can be easily printed with `println(arr)` and converted to a string