docs: fix doc comments in arrays too

cmd/tools/find_doc_comments_with_no_dots.v

@@ -16,6 +16,7 @@ fn main() {
 				&& !it.ends_with('_test.c.v'))
 		}
 	}
+	fpaths.sort()
 	mut ctx := Context{}
 	for filepath in fpaths {
 		ctx.process_fpath(filepath) or {

vlib/arrays/arrays.v

@@ -13,7 +13,7 @@ import strings
 // - flatten - reduce dimensionality of array by one. e.g. arrays.flatten([[1,2],[3,4],[5,6]]) => [1,2,3,4,5,6]
 // - each - call a callback fn, for each element of the array, similar to a.map(), but unlike it, the callback should not return anything
 
-// min returns the minimum value in the array
+// min returns the minimum value in the array.
 // Example: arrays.min([1, 2, 3, 0, 9])! // => 0
 pub fn min[T](array []T) !T {
 	if array.len == 0 {
@@ -28,7 +28,7 @@ pub fn min[T](array []T) !T {
 	return val
 }
 
-// max returns the maximum value in the array
+// max returns the maximum value in the array.
 // Example: arrays.max([1, 2, 3, 0, 9])! // => 9
 pub fn max[T](array []T) !T {
 	if array.len == 0 {
@@ -43,7 +43,7 @@ pub fn max[T](array []T) !T {
 	return val
 }
 
-// idx_min returns the index of the minimum value in the array
+// idx_min returns the index of the minimum value in the array.
 // Example: arrays.idx_min([1, 2, 3, 0, 9])! // => 3
 pub fn idx_min[T](array []T) !int {
 	if array.len == 0 {
@@ -60,7 +60,7 @@ pub fn idx_min[T](array []T) !int {
 	return idx
 }
 
-// idx_max returns the index of the maximum value in the array
+// idx_max returns the index of the maximum value in the array.
 // Example: arrays.idx_max([1, 2, 3, 0, 9])! // => 4
 pub fn idx_max[T](array []T) !int {
 	if array.len == 0 {
@@ -77,7 +77,7 @@ pub fn idx_max[T](array []T) !int {
 	return idx
 }
 
-// merge two sorted arrays (ascending) and maintain sorted order
+// merge two sorted arrays (ascending) and maintain sorted order.
 // Example: arrays.merge([1, 3, 5, 7], [2, 4, 6, 8]) // => [1, 2, 3, 4, 5, 6, 7, 8]
 @[direct_array_access]
 pub fn merge[T](a []T, b []T) []T {
@@ -122,11 +122,9 @@ pub fn append[T](a []T, b []T) []T {
 	return m
 }
 
-// group n arrays into a single array of arrays with n elements
-//
+// group n arrays into a single array of arrays with n elements.
 // This function is analogous to the "zip" function of other languages.
 // To fully interleave two arrays, follow this function with a call to `flatten`.
-//
 // NOTE: An error will be generated if the type annotation is omitted.
 // Example: arrays.group[int]([1, 2, 3], [4, 5, 6]) // => [[1, 4], [2, 5], [3, 6]]
 pub fn group[T](arrs ...[]T) [][]T {
@@ -155,7 +153,7 @@ pub fn group[T](arrs ...[]T) [][]T {
 	return [][]T{}
 }
 
-// chunk array into a single array of arrays where each element is the next `size` elements of the original
+// chunk array into a single array of arrays where each element is the next `size` elements of the original.
 // Example: arrays.chunk([1, 2, 3, 4, 5, 6, 7, 8, 9], 2)) // => [[1, 2], [3, 4], [5, 6], [7, 8], [9]]
 pub fn chunk[T](array []T, size int) [][]T {
 	// allocate chunk array
@@ -181,8 +179,7 @@ pub fn chunk[T](array []T, size int) [][]T {
 	return chunks
 }
 
-// chunk_while splits the input array `a` into chunks of varying length,
-// using the `predicate`, passing to it pairs of adjacent elements `before` and `after`.
+// chunk_while splits the input array `a` into chunks of varying length, using the `predicate`, passing to it pairs of adjacent elements `before` and `after`.
 // Each chunk, will contain all ajdacent elements, for which the `predicate` returned true.
 // The chunks are split *between* the `before` and `after` elements, for which the `predicate` returned false.
 // Example: assert arrays.chunk_while([0,9,2,2,3,2,7,5,9,5],fn(x int,y int)bool{return x<=y})==[[0,9],[2,2,3],[2,7],[5,9],[5]]
@@ -244,7 +241,7 @@ pub fn window[T](array []T, attr WindowAttribute) [][]T {
 	return windows
 }
 
-// sum up array, return an error, when the array has no elements
+// sum up array, return an error, when the array has no elements.
 // Example: arrays.sum([1, 2, 3, 4, 5])! // => 15
 pub fn sum[T](array []T) !T {
 	if array.len == 0 {
@@ -301,8 +298,7 @@ pub fn reduce_indexed[T](array []T, reduce_op fn (idx int, acc T, elem T) T) !T
 	}
 }
 
-// filter_indexed filters elements based on `predicate` function
-// being invoked on each element with its index in the original array.
+// filter_indexed filters elements based on `predicate` function being invoked on each element with its index in the original array.
 pub fn filter_indexed[T](array []T, predicate fn (idx int, elem T) bool) []T {
 	mut result := []T{cap: array.len}
 
@@ -352,7 +348,7 @@ pub fn fold_indexed[T, R](array []T, init R, fold_op fn (idx int, acc R, elem T)
 	return value
 }
 
-// flatten flattens n + 1 dimensional array into n dimensional array
+// flatten flattens n + 1 dimensional array into n dimensional array.
 // Example: arrays.flatten[int]([[1, 2, 3], [4, 5]]) // => [1, 2, 3, 4, 5]
 pub fn flatten[T](array [][]T) []T {
 	// calculate required capacity
@@ -376,8 +372,7 @@ pub fn flatten[T](array [][]T) []T {
 	return result
 }
 
-// flat_map creates a new array populated with the flattened result of calling transform function
-// being invoked on each element of `list`.
+// flat_map creates a new array populated with the flattened result of calling transform function being invoked on each element of `list`.
 pub fn flat_map[T, R](array []T, transform fn (elem T) []R) []R {
 	mut result := [][]R{cap: array.len}
 
@@ -388,8 +383,7 @@ pub fn flat_map[T, R](array []T, transform fn (elem T) []R) []R {
 	return flatten(result)
 }
 
-// flat_map_indexed creates a new array populated with the flattened result of calling the `transform` function
-// being invoked on each element with its index in the original array.
+// flat_map_indexed creates a new array with the flattened result of calling the `transform` fn, invoked on each idx,elem pair from the original.
 pub fn flat_map_indexed[T, R](array []T, transform fn (idx int, elem T) []R) []R {
 	mut result := [][]R{cap: array.len}
 
@@ -400,8 +394,7 @@ pub fn flat_map_indexed[T, R](array []T, transform fn (idx int, elem T) []R) []R
 	return flatten(result)
 }
 
-// map_indexed creates a new array populated with the result of calling the `transform` function
-// being invoked on each element with its index in the original array.
+// map_indexed creates a new array with the result of calling the `transform` fn, invoked on each idx,elem pair from the original.
 pub fn map_indexed[T, R](array []T, transform fn (idx int, elem T) R) []R {
 	mut result := []R{cap: array.len}
 
@@ -431,7 +424,7 @@ pub fn group_by[K, V](array []V, grouping_op fn (val V) K) map[K][]V {
 	return result
 }
 
-// concatenate an array with an arbitrary number of additional values
+// concatenate an array with an arbitrary number of additional values.
 //
 // NOTE: if you have two arrays, you should simply use the `<<` operator directly
 // Example: arrays.concat([1, 2, 3], 4, 5, 6) == [1, 2, 3, 4, 5, 6] // => true
@@ -446,7 +439,7 @@ pub fn concat[T](a []T, b ...T) []T {
 	return m
 }
 
-// returns the smallest element >= val, requires `array` to be sorted
+// returns the smallest element >= val, requires `array` to be sorted.
 // Example: arrays.lower_bound([2, 4, 6, 8], 3)! // => 4
 pub fn lower_bound[T](array []T, val T) !T {
 	if array.len == 0 {
@@ -469,7 +462,7 @@ pub fn lower_bound[T](array []T, val T) !T {
 	}
 }
 
-// returns the largest element <= val, requires `array` to be sorted
+// returns the largest element <= val, requires `array` to be sorted.
 // Example: arrays.upper_bound([2, 4, 6, 8], 3)! // => 2
 pub fn upper_bound[T](array []T, val T) !T {
 	if array.len == 0 {
@@ -492,7 +485,7 @@ pub fn upper_bound[T](array []T, val T) !T {
 	}
 }
 
-// binary search, requires `array` to be sorted, returns index of found item or error.
+// binary_search, requires `array` to be sorted, returns index of found item or error.
 // Binary searches on sorted lists can be faster than other array searches because at maximum
 // the algorithm only has to traverse log N elements
 // Example: arrays.binary_search([1, 2, 3, 4], 4)! // => 3
@@ -514,9 +507,10 @@ pub fn binary_search[T](array []T, target T) !int {
 	return error('')
 }
 
-// rotate_left rotates the array in-place such that the first `mid` elements of the array move to the end
-// while the last `array.len - mid` elements move to the front. After calling `rotate_left`, the element
-// previously at index `mid` will become the first element in the array.
+// rotate_left rotates the array in-place.
+// It does it in such a way, that the first `mid` elements of the array, move to the end,
+// while the last `array.len - mid` elements move to the front.
+// After calling `rotate_left`, the element previously at index `mid` will become the first element in the array.
 // Example:
 // ```v
 // mut x := [1,2,3,4,5,6]
@@ -532,9 +526,10 @@ pub fn rotate_left[T](mut array []T, mid int) {
 	}
 }
 
-// rotate_right rotates the array in-place such that the first `array.len - k` elements of the array move to the end
-// while the last `k` elements move to the front. After calling `rotate_right`, the element previously at index `array.len - k`
-// will become the first element in the array.
+// rotate_right rotates the array in-place.
+// It does it in such a way, that the first `array.len - k` elements of the array, move to the end,
+// while the last `k` elements move to the front.
+// After calling `rotate_right`, the element previously at index `array.len - k` will become the first element in the array.
 // Example:
 // ```v
 // mut x := [1,2,3,4,5,6]
@@ -687,7 +682,7 @@ pub fn copy[T](mut dst []T, src []T) int {
 	return min
 }
 
-// determines if T can be copied using `memcpy`
+// can_copy_bits determines if T can be copied using `memcpy`.
 // false if autofree needs to intervene
 // false if type is not copyable e.g. map
 fn can_copy_bits[T]() bool {
@@ -758,9 +753,9 @@ pub fn join_to_string[T](array []T, separator string, transform fn (elem T) stri
 	return sb.str()
 }
 
-// partition splits the original array into pair of lists,
-// where first list contains elements for which predicate yielded true,
-// while second list contains elements for which predicate yielded false
+// partition splits the original array into pair of lists.
+// The first list contains elements for which the predicate fn returned true,
+// while the second list contains elements for which the predicate fn returned false.
 pub fn partition[T](array []T, predicate fn (elem T) bool) ([]T, []T) {
 	mut matching, mut non_matching := []T{}, []T{}
 	for item in array {
@@ -773,15 +768,15 @@ pub fn partition[T](array []T, predicate fn (elem T) bool) ([]T, []T) {
 	return matching, non_matching
 }
 
-// each calls the callback fn `cb`, for each element of the given array `a`
+// each calls the callback fn `cb`, for each element of the given array `a`.
 pub fn each[T](a []T, cb fn (elem T)) {
 	for item in a {
 		cb(item)
 	}
 }
 
-// each_indexed calls the callback fn `cb`, for each element of the given array `a`,
-// passing it both the index of the current element, and the element itself
+// each_indexed calls the callback fn `cb`, for each element of the given array `a`.
+// It passes the callback both the index of the current element, and the element itself.
 pub fn each_indexed[T](a []T, cb fn (i int, e T)) {
 	for idx, item in a {
 		cb(idx, item)

vlib/arrays/diff/diff.v

@@ -2,8 +2,7 @@ module diff
 
 import strings
 
-// DiffChange contains one or more deletions or inserts
-// at one position in two arrays.
+// DiffChange contains one or more deletions or inserts at one position in two arrays.
 pub struct DiffChange {
 pub mut:
 	a   int // position in input a []T

vlib/arrays/index_of.v

@@ -1,7 +1,6 @@
 module arrays
 
-// index_of_first returns the index of the first element of `array`, for which the predicate
-// function returns true.
+// index_of_first returns the index of the first element of `array`, for which the predicate fn returns true.
 // If predicate does not return true for any of the elements, then index_of_first will return -1.
 // Example: arrays.index_of_first([4,5,0,7,0,9], fn(idx int, x int) bool { return x == 0 }) == 2
 pub fn index_of_first[T](array []T, predicate fn (idx int, elem T) bool) int {
@@ -13,8 +12,7 @@ pub fn index_of_first[T](array []T, predicate fn (idx int, elem T) bool) int {
 	return -1
 }
 
-// index_of_last returns the index of the last element of `array`, for which the predicate
-// function returns true.
+// index_of_last returns the index of the last element of `array`, for which the predicate fn returns true.
 // If predicate does not return true for any of the elements, then index_of_last will return -1.
 // Example: arrays.index_of_last([4,5,0,7,0,9], fn(idx int, x int) bool { return x == 0 }) == 4
 pub fn index_of_last[T](array []T, predicate fn (idx int, elem T) bool) int {

vlib/arrays/map_of.v

@@ -1,8 +1,7 @@
 module arrays
 
-// map_of_indexes returns a map, where each key is an unique value in `array`,
-// and each value for that key is an array, containing the indexes in `array`,
-// where that value has been found.
+// map_of_indexes returns a map, where each key is an unique value in `array`.
+// Each value in that map for that key, is an array, containing the indexes in `array`, where that value has been found.
 // Example: arrays.map_of_indexes([1,2,3,4,4,2,1,4,4,999]) == {1: [0, 6], 2: [1, 5], 3: [2], 4: [3, 4, 7, 8], 999: [9]}
 pub fn map_of_indexes[T](array []T) map[T][]int {
 	mut result := map[T][]int{}
@@ -16,8 +15,8 @@ pub fn map_of_indexes[T](array []T) map[T][]int {
 	return result
 }
 
-// map_of_counts returns a map, where each key is an unique value in `array`,
-// and each value for that key is how many times that value occurs in `array`.
+// map_of_counts returns a map, where each key is an unique value in `array`.
+// Each value in that map for that key, is how many times that value occurs in `array`.
 // It can be useful for building histograms of discrete measurements.
 // Example: arrays.map_of_counts([1,2,3,4,4,2,1,4,4]) == {1: 2, 2: 2, 3: 1, 4: 4}
 pub fn map_of_counts[T](array []T) map[T]int {

vlib/arrays/parallel/parallel.v

@@ -19,9 +19,8 @@ fn limited_workers(max_workers int, ilen int) int {
 	return workers
 }
 
-// run lets the user run an array of input with a
-// user provided function in parallel. It limits the number of
-// worker threads to min(num_workers, num_cpu)
+// run lets the user run an array of input with a user provided function in parallel.
+// It limits the number of worker threads to min(num_workers, num_cpu).
 // The function aborts if an error is encountered.
 // Example: parallel.run([1, 2, 3, 4, 5], 2, fn (i) { println(i) })
 pub fn run[T](input []T, worker fn (T), opt Params) {
@@ -58,9 +57,8 @@ struct Task[T, R] {
 	result R
 }
 
-// amap lets the user run an array of input with a
-// user provided function in parallel. It limits the number of
-// worker threads to max number of cpus.
+// amap lets the user run an array of input with a user provided function in parallel.
+// It limits the number of worker threads to max number of cpus.
 // The worker function can return a value. The returning array maintains the input order.
 // Any error handling should have happened within the worker function.
 // Example: squares := parallel.amap([1, 2, 3, 4, 5], 2, fn (i) { return i * i })

vlib/arrays/reverse_iterator.v

@@ -1,15 +1,15 @@
 module arrays
 
-// ReverseIterator provides a convenient way to iterate in reverse over all elements of an array,
-// without making allocations, using this syntax: `for elem in arrays.reverse_iterator(a) {` .
+// ReverseIterator provides a convenient way to iterate in reverse over all elements of an array without allocations.
+// I.e. it allows you to use this syntax: `for elem in arrays.reverse_iterator(a) {` .
 pub struct ReverseIterator[T] {
 mut:
 	a []T
 	i int
 }
 
-// reverse_iterator can be used to iterate over the elements in an array using this syntax:
-// `for elem in arrays.reverse_iterator(a) {` .
+// reverse_iterator can be used to iterate over the elements in an array.
+// i.e. you can use this syntax: `for elem in arrays.reverse_iterator(a) {` .
 pub fn reverse_iterator[T](a []T) ReverseIterator[T] {
 	return ReverseIterator[T]{
 		a: a