Doc examples for new slices and maps packages

[ben...@gmail.com]

Hi folks,

I notice there's no examples in the API docs for "slices" and "maps".

A lot of the functions are pretty obvious, like slices.Contains, slices.Clone, and maps.Keys. But the new Sort* functions, and other functions that use a new-style cmp function, would really benefit from a couple of simple examples. By contrast, the existing sort.Slice* functions have nice examples.

One other thing I noticed: slices.CompactFunc doesn't have quite enough info (and an example is probably helpful there, too). It says "CompactFunc is like Compact but uses a comparison function." But it's an equality function, not really a comparison (cmp) function, and either way, the doc comment doesn't explain how the function is used. Could be tweaked to "... but uses eq(a, b) to determine whether two elements are equal." Or even terser (like maps.EqualFunc): "... but compares values using eq." For comparison, slices.ContainsFunc's doc says what it does with its function.

In any case, I wanted to see if there was appetite for adding examples here -- if so, I'm happy to submit a patch.

-Ben

[Ian Lance Taylor]

Good examples are always welcome. Thanks.

Ian

[ben...@gmail.com]

Added examples, and a couple of doc comment tweaks:

https://go-review.googlesource.com/c/go/+/505095

I may have gone overboard with the slices examples, but I figure with generics function signatures being somewhat complex, an example one most of these is helpful.

-Ben