Apply suggestions from code review

Co-authored-by: Richard Sill <[email protected]>

Author: gem-neo4j

modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc

@@ -46,7 +46,7 @@ RETURN coll.min([1.5, 2, 5.4, 0, 4]);
 RETURN coll.remove(['a', 'a', 'b', 'c', 'd'], 2);
 RETURN coll.sort([3, 1, 4, 2, 'a', 'c', 'b']);
 ----
-| Introduction of eight new collection based Cypher functions.
+| Introduction of eight new collection-based Cypher functions.
 For more information, see xref:functions/list.adoc[List functions - lists].
 
 |===

modules/ROOT/pages/functions/list.adoc

@@ -51,7 +51,7 @@ CREATE
 .Considerations
 |===
 | `coll.distinct(null)` returns `null`.
-| The order of the first occurrences is preserved.
+| The order of the first occurrences of the distinct values is preserved.
 |===
 
 .+coll.distinct()+
@@ -103,9 +103,9 @@ A `LIST<ANY>` containing only unique values is returned.
 .Details
 |===
 | *Syntax* 3+| `coll.flatten(list [, depth])`
-| *Description* 3+| Returns a list flattened to the given depth.
+| *Description* 3+| Returns a list flattened to the given nesting depth.
 .3+| *Arguments* | *Name* | *Type* | *Description*
-| `list` | `LIST<ANY>` | A list to be flattened.
+| `list` | `LIST<ANY>` | A nested list to be flattened.
 | `depth` | `INTEGER` | The maximum depth to flatten to (default value: 1).
 | *Returns* 3+| `LIST<ANY>`
 |===
@@ -171,7 +171,7 @@ A `LIST<ANY>` with any inner lists up to a nesting depth of 1 (default depth) fl
 .Details
 |===
 | *Syntax* 3+| `coll.indexOf(list, value)`
-| *Description* 3+| Returns the index for the first match of value in the given list, if the value is not present, -1 is returned.
+| *Description* 3+| Returns the index for the first match of a value in the given list or -1 if the value is not present.
 .3+| *Arguments* | *Name* | *Type* | *Description*
 | `list` | `LIST<ANY>` | A list to be searched.
 | `value` | `ANY` | A value to search for.
@@ -252,7 +252,7 @@ The `INTEGER` -1 representing that the value is not found.
 | `coll.insert(null, null, value)` returns `null`.
 | `coll.insert(list, null, value)` returns `null`.
 | `coll.insert(null, 1, value)` returns `null`.
-| If the given `index` is negative or larger than the size of the given list, an error will be returned.
+| If the given `index` is negative or larger than the size of the given list, an error is returned.
 
 |===
 
@@ -387,7 +387,7 @@ The minimum value found in the given list based on Cypher's ordering.
 | `coll.remove(null, null)` returns `null`.
 | `coll.remove(null, index)` returns `null`.
 | `coll.remove(list, null)` returns `null`.
-| If the given `index` is negative or larger than the size of the given list, an error will be returned.
+| If the given `index` is negative or larger than the size of the given list, an error is returned.
 
 |===
 
@@ -403,7 +403,7 @@ RETURN coll.remove([true, 'a', 1, 5.4], 1)
 ----
 // end::functions_list_remove[]
 
-The original list with the value at the given index removed and all items following shifted forward by 1.
+The original list with the value at the given index removed and all items following shifted by 1.
 
 .Result
 [role="queryresult",options="header,footer",cols="1*<m"]