strings: EqualFold doc could be clearer

[kevinburke]

The doc for EqualFold says:

EqualFold reports whether s and t, interpreted as UTF-8 strings, are equal under Unicode case-folding.

I have been using Go for over five years now and had no idea what "Unicode case-folding" was until about three minutes ago. Previously I had implemented this by calling strings.ToLower on each side, which is slow and unnecessary. More commonly I believe the EqualFold functionality is known as "case insensitive matching." Users who are searching the strings documentation for the phrase "case insensitive" will find nothing, when they should be finding this function.

Scanning Github this seems like a common mistake:

https://github.com/sachin-varade/network/blob/5d4ab4a3757603b8c0ba9a9df7bc9e0ff92ad102/app/utils/setup/chaincode/processors/read_ledger.go#L172
https://github.com/projectriri/bot-gateway/blob/d4402bd4ac0d4478bd86e585ca83e9d3fc1c140e/converters/cqhttp-ubm-conv/cqhttp-ubm-conv.go#L79

Several Go vetters/linters have checks for this construction that suggest using EqualFold instead:

https://github.com/dominikh/go-tools/blob/1da3061645b400d55be4855f104d8a68ca0a61e5/staticcheck/testdata/src/CheckToLowerToUpperComparison/CheckToLowerToUpperComparison.go

StackOverflow answers suggesting the use of EqualFold have 35,000 views and 10,000 views, respectively.

https://stackoverflow.com/q/24836044/329700
https://stackoverflow.com/q/30196780/329700

[smasher164]

I agree that this doc can be made clearer. How about adding a clause to say that it basically does a more general form of case-insensitive matching? Something like:

EqualFold reports whether s and t, interpreted as UTF-8 strings, are equal under Unicode case-folding, a generalization of case-insensitivity.

[gopherbot]

Change https://golang.org/cl/196717 mentions this issue: strings, bytes: clarify usage of EqualFolds

[andrewmed]

I opened PR for this, fixing also docs for EqualFold() in bytes package.
Formally, better word here seems to be "caseless" (as in the section 13.3 of Unicode Standard) but I picked up more conventional "case insensitive"
This is my first PR