slices, maps: add examples; doc comment fixes

There are currently no examples in the new slices and maps package, so
add some. This adds examples for most functions in the slices package
except the very obvious ones, and adds examples for the DeleteFunc and
EqualFunc functions in the maps package.

Also clarify/correct a few doc comments:

* EqualFunc takes an "equality" function, not a "comparison" function
* It's confusing for Delete and DeleteFunc to say they "do not create a
  new slice", as they do return a new slice. They already say they
  "return the modified slice" which is enough.
* Similar for Compact, and mention that it returns the modified slice
  (and say why)
* Note that CompactFunc keeps the first element in equal runs
* Say what cmp is in SortStableFunc and IsSortedFunc
* Say that MinFunc and MaxFunc return the first value

Change-Id: I59c7bb1c7cabc4986d81018a5aaf5b712d3310f2
Reviewed-on: https://go-review.googlesource.com/c/go/+/505095
Reviewed-by: Carlos Amedee <carlos@golang.org>
Reviewed-by: Emmanuel Odeke <emmanuel@orijtech.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>
Run-TryBot: Ian Lance Taylor <iant@google.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>

src/maps/example_test.go

@@ -0,0 +1,45 @@
+// Copyright 2023 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package maps_test
+
+import (
+	"fmt"
+	"maps"
+	"strings"
+)
+
+func ExampleDeleteFunc() {
+	m := map[string]int{
+		"one":   1,
+		"two":   2,
+		"three": 3,
+		"four":  4,
+	}
+	maps.DeleteFunc(m, func(k string, v int) bool {
+		return v%2 != 0 // delete odd values
+	})
+	fmt.Println(m)
+	// Output:
+	// map[four:4 two:2]
+}
+
+func ExampleEqualFunc() {
+	m1 := map[int]string{
+		1:    "one",
+		10:   "Ten",
+		1000: "THOUSAND",
+	}
+	m2 := map[int][]byte{
+		1:    []byte("One"),
+		10:   []byte("Ten"),
+		1000: []byte("Thousand"),
+	}
+	eq := maps.EqualFunc(m1, m2, func(v1 string, v2 []byte) bool {
+		return strings.ToLower(v1) == strings.ToLower(string(v2))
+	})
+	fmt.Println(eq)
+	// Output:
+	// true
+}