From 55989b3c2c5da7563c8103d229d4f9727bdc806c Mon Sep 17 00:00:00 2001
From: Nick Treleaven <n@trelsoft.com>
Date: Tue, 30 Jun 2020 13:37:02 +0100
Subject: [PATCH] doc: split array example & some tweaks (#5564)

---
 doc/docs.md | 49 ++++++++++++++++++++++++++++++-------------------
 1 file changed, 30 insertions(+), 19 deletions(-)

diff --git a/doc/docs.md b/doc/docs.md
index ef5cbf7ace..7e10aac02c 100644
--- a/doc/docs.md
+++ b/doc/docs.md
@@ -389,10 +389,38 @@ println(s) // "hello\nworld"
 mut nums := [1, 2, 3]
 println(nums) // "[1, 2, 3]"
 println(nums[1]) // "2"
+nums[1] = 5
+println(nums) // "[1, 5, 3]"
 
+println(nums.len) // "3"
+nums = [] // The array is now empty
+println(nums.len) // "0"
+
+// Declare an empty array:
+users := []int{}
+
+// We can also preallocate a certain amount of elements.
+ids := []int{ len: 50, init: 0 } // This creates an array with 50 zeros
+```
+
+The type of an array is determined by the first element:
+* `[1, 2, 3]` is an array of ints (`[]int`).
+* `['a', 'b']` is an array of strings (`[]string`).
+
+If V is unable to infer the type of an array, the user can explicitly specify it for the first element: `[byte(0x0E), 0x1F, 0xBA, 0x0E]`
+
+V arrays are homogeneous (all elements must have the same type). This means that code like `[1, 'a']` will not compile.
+
+`.len` field returns the length of the array. Note that it's a read-only field,
+and it can't be modified by the user. Exported fields are read-only by default in V.
+See [Access modifiers](#access-modifiers).
+
+```v
+mut nums := [1, 2, 3]
 nums << 4
 println(nums) // "[1, 2, 3, 4]"
 
+// append array
 nums << [5, 6, 7]
 println(nums) // "[1, 2, 3, 4, 5, 6, 7]"
 
@@ -402,31 +430,14 @@ names << 'Sam'
 // names << 10  <-- This will not compile. `names` is an array of strings.
 println(names.len) // "3"
 println('Alex' in names) // "false"
-
-names = [] // The array is now empty
-
-// Declare an empty array:
-users := []User{}
-
-// We can also preallocate a certain amount of elements.
-ids := []int{ len: 50, init: 0 } // This creates an array with 50 zeros
 ```
 
-The type of an array is determined by the first element: `[1, 2, 3]` is an array of ints (`[]int`).
-
-`['a', 'b']` is an array of strings (`[]string`).
-
-If V is unable to infer the type of an array, the user can explicitly specify it for the first element: `[byte(0x0E), 0x1F, 0xBA, 0x0E]`
-
-V arrays are homogeneous (all elements must have the same type). This means that code like `[1, 'a']` will not compile.
-
 `<<` is an operator that appends a value to the end of the array.
 It can also append an entire array.
 
-`.len` field returns the length of the array. Note, that it's a read-only field,
-and it can't be modified by the user. Exported fields are read-only by default in V.
+`val in array` returns true if the array contains `val`. See [`in` operator](#in-operator).
 
-`val in array` returns true if the array contains `val`.
+#### Array methods
 
 All arrays can be easily printed with `println(arr)` and converted to a string
 with `s := arr.str()`.