From 02f72c823050ef72f359bfd0e022011486b15f56 Mon Sep 17 00:00:00 2001
From: Nick Treleaven <ntrel002@gmail.com>
Date: Sun, 27 Mar 2022 12:28:15 +0100
Subject: [PATCH] builtin: improve docs for array methods that take an `it`
 expression, like .map, .filter etc (#13836)

Move explanation about boolean `it` expressions to `filter`, as `sort`
doesn't take a boolean expression. Also move `any` example.
Add 2 filter examples.
Add map example from docs.md.
---
 vlib/builtin/array.v | 52 ++++++++++++++++++++++++++++----------------
 1 file changed, 33 insertions(+), 19 deletions(-)

diff --git a/vlib/builtin/array.v b/vlib/builtin/array.v
index e6253d5eb3..2d7b712fb9 100644
--- a/vlib/builtin/array.v
+++ b/vlib/builtin/array.v
@@ -667,7 +667,17 @@ pub fn (a &array) free() {
 // Ignore the function signature. `filter` does not take an actual callback. Rather, it
 // takes an `it` expression.
 //
-// Example: array.filter(it % 2 == 1) // will yield a new array of only odd elements
+// Certain array functions (`filter` `any` `all`) support a simplified
+// domain-specific-language by the backend compiler to make these operations
+// more idiomatic to V. These functions are described here, but their implementation
+// is compiler specific.
+//
+// Each function takes a boolean test expression as its single argument.
+// These test expressions may use `it` as a pointer to a single element at a time.
+//
+// Example: array.filter(it < 5) // create an array of elements less than 5
+// Example: array.filter(it % 2 == 1) // create an array of only odd elements
+// Example: array.filter(it.name[0] == `A`) // create an array of elements whose `name` field starts with 'A'
 pub fn (a array) filter(predicate fn (voidptr) bool) array
 
 // any tests whether at least one element in the array passes the test.
@@ -677,6 +687,7 @@ pub fn (a array) filter(predicate fn (voidptr) bool) array
 // it returns `false`. It doesn't modify the array.
 //
 // Example: array.any(it % 2 == 1) // will return true if any element is odd
+// Example: array.any(it.name == 'Bob') // will yield `true` if any element has `.name == 'Bob'`
 pub fn (a array) any(predicate fn (voidptr) bool) bool
 
 // all tests whether all elements in the array pass the test
@@ -689,34 +700,37 @@ pub fn (a array) any(predicate fn (voidptr) bool) bool
 pub fn (a array) all(predicate fn (voidptr) bool) bool
 
 // map creates a new array populated with the results of calling a provided function
-// on every element in the calling array
+// on every element in the calling array.
+// It also accepts an `it` expression.
+//
+// Example:
+// ```v
+// words := ['hello', 'world']
+// r1 := words.map(it.to_upper())
+// assert r1 == ['HELLO', 'WORLD']
+//
+// // map can also accept anonymous functions
+// r2 := words.map(fn (w string) string {
+// 	return w.to_upper()
+// })
+// assert r2 == ['HELLO', 'WORLD']
+// ```
 pub fn (a array) map(callback fn (voidptr) voidptr) array
 
-// sort sorts an array in place.
+// sort sorts the array in place.
 // Ignore the function signature. Passing a callback to `.sort` is not supported
 // for now. Consider using the `.sort_with_compare` method if you need it.
 //
-// Instead, a very simple syntax is available to you for custom sorting and more.
-//
-// Certain array functions (`filter` `any` `all` and `sort`) support a simplified
-// domain-specific-language by the backend compiler to make these operations
-// more idiomatic to V. These functions are described here, but their implementation
-// is compiler specific.
-//
-// Each function takes a boolean test expression as its single argument.
-// These test expressions may use certain 'magic' variables depending on their context:
-// - `sort` may use `a` and `b` as pointers to two elements
-//   giving you direct access to those objects
-// - `filter`, `any`, and `all` may use `it` as a pointer to a single element at a time.
+// sort can take a boolean test expression as its single argument.
+// The expression uses 2 'magic' variables `a` and `b` as pointers to the two elements
+// being compared.
 //
 // Example: array.sort() // will sort the array in ascending order
 // Example: array.sort(b < a) // will sort the array in decending order
 // Example: array.sort(b.name < a.name) // will sort descending by the .name field
-// Example: array.filter(it % 2 == 1) // will yield a new array of only odd elements
-// Example: array.any(it.name == 'Bob') // will yield `true` if any element has `.name == 'Bob'`
 pub fn (mut a array) sort(callback fn (voidptr, voidptr) int)
 
-// sort_with_compare sorts array in-place using the results of the
+// sort_with_compare sorts the array in-place using the results of the
 // given function to determine sort order.
 //
 // The function should return one of three values:
@@ -724,7 +738,7 @@ pub fn (mut a array) sort(callback fn (voidptr, voidptr) int)
 // - `1`  when `b` should come before `a` ( `b < a` )
 // - `0`  when the order cannot be determined ( `a == b` )
 //
-// ### Example:
+// Example:
 // ```v
 // fn main() {
 // 	mut a := ['hi', '1', '5', '3']