arrays,docs: remove arrays.zip; improve docs (#13082)

vlib/arrays/arrays.v

@@ -6,7 +6,8 @@ module arrays
 // - merge - combine two sorted arrays and maintain sorted order
 // - chunk - chunk array to arrays with n elements
 // - window - get snapshots of the window of the given size sliding along array with the given step, where each snapshot is an array
-// - TODO: zip - merge two arrays by interleaving e.g. arrays.zip([1,3,5], [2,4,6]) => [1,2,3,4,5,6]
+// - group - merge two arrays by interleaving e.g. arrays.group([1,3,5], [2,4,6]) => [[1,2],[3,4],[5,6]]
+// - flatten - reduce dimensionality of array by one. e.g. arrays.flatten([[1,2],[3,4],[5,6]]) => [1,2,3,4,5,6]
 
 // min returns the minimum value in the array
 // Example: arrays.min([1,2,3,0,9]) // => 0
@@ -107,7 +108,11 @@ pub fn merge<T>(a []T, b []T) []T {
 }
 
 // group n arrays into a single array of arrays with n elements
-// (an error will be generated if the type annotation is omitted)
+//
+// 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>(lists ...[]T) [][]T {
 	mut length := if lists.len > 0 { lists[0].len } else { 0 }
@@ -122,12 +127,12 @@ pub fn group<T>(lists ...[]T) [][]T {
 		mut arr := [][]T{cap: length}
 		// append all combined arrays into the resultant array
 		for ndx in 0 .. length {
-			mut zipped := []T{cap: lists.len}
+			mut grouped := []T{cap: lists.len}
 			// combine each list item for the ndx position into one array
 			for list_ndx in 0 .. lists.len {
-				zipped << lists[list_ndx][ndx]
+				grouped << lists[list_ndx][ndx]
 			}
-			arr << zipped
+			arr << grouped
 		}
 		return arr
 	}
@@ -305,30 +310,6 @@ pub fn concat<T>(a []T, b ...T) []T {
 	return m
 }
 
-// zip returns a new array by interleaving the source arrays.
-//
-// NOTE: The two arrays do not need to be equal sizes
-// Example: arrays.zip([1, 3, 5, 7], [2, 4, 6, 8, 10]) // => [1, 2, 3, 4, 5, 6, 7, 8, 10]
-pub fn zip<T>(a []T, b []T) []T {
-	mut m := []T{cap: a.len + b.len}
-	mut i := 0
-	for i < m.cap {
-		// short-circuit the rest of the loop as soon as we can
-		if i >= a.len {
-			m << b[i..]
-			break
-		}
-		if i >= b.len {
-			m << a[i..]
-			break
-		}
-		m << a[i]
-		m << b[i]
-		i++
-	}
-	return m
-}
-
 // returns the smallest element >= val, requires `arr` to be sorted
 // Example: arrays.lower_bound([2, 4, 6, 8], 3)? // => 4
 pub fn lower_bound<T>(arr []T, val T) ?T {

vlib/builtin/README.md

@@ -4,3 +4,7 @@
 It implements the builtin V types `array`, `string`, `map`.
 It also implements builtin functions like `println`, `eprintln`, `malloc`,
 `panic`, `print_backtrace`.
+
+The autogenerated documentation for builtin functions is lacking,
+so for these functions, please refer to the
+[official V documentation](https://github.com/vlang/v/blob/master/doc/docs.md).

vlib/builtin/js/builtin.v

@@ -59,12 +59,13 @@ pub fn (o Option) str() string {
 	return 'Option{ error: "$o.err" }'
 }
 
+// trace_error prints to stderr a string and a backtrace of the error
 fn trace_error(x string) {
 	eprintln('> ${@FN} | $x')
 }
 
 // error returns a default error instance containing the error given in `message`.
-// Example: `if ouch { return error('an error occurred') }`
+// Example: if ouch { return error('an error occurred') }
 [inline]
 pub fn error(message string) IError {
 	// trace_error(message)
@@ -74,7 +75,7 @@ pub fn error(message string) IError {
 }
 
 // error_with_code returns a default error instance containing the given `message` and error `code`.
-// `if ouch { return error_with_code('an error occurred', 1) }`
+// Example: if ouch { return error_with_code('an error occurred', 1) }
 [inline]
 pub fn error_with_code(message string, code int) IError {
 	// trace_error('$message | code: $code')
@@ -84,7 +85,8 @@ pub fn error_with_code(message string, code int) IError {
 	}
 }
 
-// free allows for manually freeing memory allocated at the address `ptr`. no-op on JS backend
+// free allows for manually freeing memory allocated at the address `ptr`.
+// However, this is a no-op on JS backend
 [unsafe]
 pub fn free(ptr voidptr) {
 	_ := ptr

vlib/sokol/audio/audio.v

@@ -97,42 +97,42 @@ fn C.saudio_expect() int
 
 fn C.saudio_push(frames &f32, num_frames int) int
 
-// audio.setup - setup sokol-audio
+// setup - setup sokol-audio
 pub fn setup(desc C.saudio_desc) {
 	C.saudio_setup(&desc)
 }
 
-// audio.shutdown - shutdown sokol-audio
+// shutdown - shutdown sokol-audio
 pub fn shutdown() {
 	C.saudio_shutdown()
 }
 
-// audio.is_valid - true after setup if audio backend was successfully initialized
+// is_valid - true after setup if audio backend was successfully initialized
 pub fn is_valid() bool {
 	return C.saudio_isvalid()
 }
 
-// audio.userdata - return the saudio_desc.user_data pointer
+// userdata - return the saudio_desc.user_data pointer
 pub fn user_data() voidptr {
 	return C.saudio_userdata()
 }
 
-// audio.query - return a copy of the original saudio_desc struct
+// query - return a copy of the original saudio_desc struct
 pub fn query() C.saudio_desc {
 	return C.saudio_query_desc()
 }
 
-// audio.sample_rate - return the actual sample rate
+// sample_rate - return the actual sample rate
 pub fn sample_rate() int {
 	return C.saudio_sample_rate()
 }
 
-// audio.buffer_frames - return the actual backend buffer size in number of frames
+// buffer_frames - return the actual backend buffer size in number of frames
 pub fn buffer_frames() int {
 	return C.saudio_buffer_frames()
 }
 
-// audio.channels - return the actual number of channels
+// channels - return the actual number of channels
 pub fn channels() int {
 	return C.saudio_channels()
 }
@@ -143,17 +143,17 @@ pub fn suspended() bool {
 	return C.saudio_suspended()
 }
 
-// audio.expect - get current number of frames to fill packet queue; use in combination with audio.push
+// expect - get current number of frames to fill packet queue; use in combination with audio.push
 pub fn expect() int {
 	return C.saudio_expect()
 }
 
-// audio.push - push sample frames from main thread, returns number of frames actually pushed
+// push - push sample frames from main thread, returns number of frames actually pushed
 pub fn push(frames &f32, num_frames int) int {
 	return C.saudio_push(frames, num_frames)
 }
 
-// audio.fclamp - helper function to 'clamp' a number to a certain range
+// fclamp - helper function to 'clamp' a number to a certain range
 // Example: realsample := audio.fclamp(sample, -1.0, 1.0)
 [inline]
 pub fn fclamp(x f32, flo f32, fhi f32) f32 {
@@ -166,9 +166,9 @@ pub fn fclamp(x f32, flo f32, fhi f32) f32 {
 	return x
 }
 
-// audio.min - helper function to return the smaller of two numbers
+// min - helper function to return the smaller of two numbers
 //
-// math.min returns `f32` values, this returns `int` values
+// NOTE: math.min returns `f32` values, this returns `int` values
 // Example: smaller := audio.min(1, 5) // smaller == 1
 pub fn min(x int, y int) int {
 	if x < y {
@@ -177,9 +177,9 @@ pub fn min(x int, y int) int {
 	return y
 }
 
-// audio.max - helper function to return the larger of two numbers
+// max - helper function to return the larger of two numbers
 //
-// math.max returns `f32` values, this returns `int` values
+// NOTE: math.max returns `f32` values, this returns `int` values
 // Example: larger := audio.max(1, 5) // larger == 5
 pub fn max(x int, y int) int {
 	if x < y {