From b2685c6060c0780362a3b1aa4c1e8d3f431a02b7 Mon Sep 17 00:00:00 2001
From: Swastik Baranwal <swstkbaranwal@gmail.com>
Date: Tue, 15 Dec 2020 14:01:35 +0530
Subject: [PATCH] builtin: add more docs to array.v (#7194)

---
 vlib/builtin/array.v | 33 ++++++++++++++++++++-------------
 1 file changed, 20 insertions(+), 13 deletions(-)

diff --git a/vlib/builtin/array.v b/vlib/builtin/array.v
index e15b4f642d..5054a121db 100644
--- a/vlib/builtin/array.v
+++ b/vlib/builtin/array.v
@@ -5,16 +5,18 @@ module builtin
 
 import strings
 
+// array is a struct used for denoting array types in V
 pub struct array {
 pub:
-	element_size int
+	element_size int // size in bytes of one element in the array.
 pub mut:
-	data         voidptr // Using a void pointer allows to implement arrays without generics and without generating
-	// extra code for every type.
-	len          int
-	cap          int
+	data         voidptr
+	len          int // length of the array.
+	cap          int // capacity of the array.
 }
 
+// array.data uses a void pointer, which allows implementing arrays without generics and without generating
+// extra code for every type.
 // Internal function, used by V (`nums := []int`)
 fn __new_array(mylen int, cap int, elm_size int) array {
 	cap_ := if cap < mylen { mylen } else { cap }
@@ -415,6 +417,7 @@ pub fn (mut a3 array) push_many(val voidptr, size int) {
 	a3.len += size
 }
 
+// reverse_in_place reverses existing array data, modifying original array.
 pub fn (mut a array) reverse_in_place() {
 	if a.len < 2 {
 		return
@@ -580,8 +583,8 @@ pub fn (mut a []int) sort() {
 	a.sort_with_compare(compare_ints)
 }
 
-// index returns the index of the first element equal to the given value,
-// or -1 if the value is not found in the array.
+// index returns the first index at which a given element can be found in the array
+// or -1 if the value is not found.
 pub fn (a []string) index(v string) int {
 	for i in 0 .. a.len {
 		if a[i] == v {
@@ -591,8 +594,8 @@ pub fn (a []string) index(v string) int {
 	return -1
 }
 
-// index returns the index of the first element equal to the given value,
-// or -1 if the value is not found in the array.
+// index returns the first index at which a given element can be found in the array
+// or -1 if the value is not found.
 pub fn (a []int) index(v int) int {
 	for i in 0 .. a.len {
 		if a[i] == v {
@@ -602,8 +605,8 @@ pub fn (a []int) index(v int) int {
 	return -1
 }
 
-// index returns the index of the first element equal to the given value,
-// or -1 if the value is not found in the array.
+// index returns the first index at which a given element can be found in the array
+// or -1 if the value is not found.
 pub fn (a []byte) index(v byte) int {
 	for i in 0 .. a.len {
 		if a[i] == v {
@@ -613,6 +616,8 @@ pub fn (a []byte) index(v byte) int {
 	return -1
 }
 
+// index returns the first index at which a given element can be found in the array
+// or -1 if the value is not found.
 pub fn (a []rune) index(v rune) int {
 	for i in 0 .. a.len {
 		if a[i] == v {
@@ -622,8 +627,8 @@ pub fn (a []rune) index(v rune) int {
 	return -1
 }
 
-// index returns the index of the first element equal to the given value,
-// or -1 if the value is not found in the array.
+// index returns the first index at which a given element can be found in the array
+// or -1 if the value is not found.
 // TODO is `char` type yet in the language?
 pub fn (a []char) index(v char) int {
 	for i in 0 .. a.len {
@@ -681,6 +686,8 @@ pub fn (a []f32) eq(a2 []f32) bool {
 	return array_eq(a, a2)
 }
 */
+// eq checks if the arrays have the same elements or not.
+// TODO: make it work with all types.
 pub fn (a1 []string) eq(a2 []string) bool {
 	// return array_eq(a, a2)
 	if a1.len != a2.len {