x/pkgsite: strings.Trim misleading documentation

[Patrick-ring-motive]

What is the URL of the page with the issue?

https://pkg.go.dev/strings

What is your user agent?

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36

Screenshot

No response

What did you do?

I'm working on creating a package that extends the strings from the standard library and noticed a possible documentation oversight. The following functions in the strings package all claim to return a slice when they actually return a string. Maybe the author is considering a string as a special type of slice but based on how it reads I would expect the return type to be []string not string.

func Trim(s, cutset string) string
func TrimFunc(s string, f func(rune) bool) string
func TrimLeft(s, cutset string) string
func TrimLeftFunc(s string, f func(rune) bool) string
func TrimPrefix(s, prefix string) string
func TrimRight(s, cutset string) string
func TrimRightFunc(s string, f func(rune) bool) string
func TrimSpace(s string) string
func TrimSuffix(s, suffix string) string

What did you see happen?

The Trim* functions in the strings package all claim to return a slice when they actually return a string.

What did you expect to see?

Maybe the author is considering a string as a special type of slice but based on how it reads I would expect the return type to be []string not string.

[seankhliao]

the docs are correct, a string can be sliced, and it's relevant to whether the original string can be garbage collected.

[Patrick-ring-motive]

the docs are correct, a string can be sliced, and it's relevant to whether the original string can be garbage collected.

You get how this is misleading though right? I mean I can agree with you but in golang slices have a very specific meaning that is different from what is being referenced here.

[ALTree]

You get how this is misleading though right? I mean I can agree with you but in golang slices have a very specific meaning that is different from what is being referenced here.

Not really, this kind of language is used in the Language Specification too, for example:

Except for untyped strings, if the sliced operand is a string or slice, the result of the slice operation is

i.e. strings can be sliced and the result of the operation returns "a slice" of that string. The documentation wording is consistent with this.

[Patrick-ring-motive]

@seankhliao @ALTree Your example from the language spec further supports what I am getting at actually. When the spec talks about slicing a string it is using slice as a verb and performing a slice action on a string. When the spec talks about "a slice" using the noun, it is talking about the variable length arrays. See it even goes out of its way to specify the difference. "if the sliced operand is a string or slice". If they were considered the same then they could have just said "if the sliced operand is a slice". In the strings package, the Trim functions say specifically "Trim returns a slice" not "a sliced string". You can't tell me that this is unambiguous. Why are you arguing against clarity in the documentation?

Edit: I'm making this change to my golang docs mirror

From

Trim returns a slice of the string s with all leading and trailing Unicode code points contained in cutset removed.

To

Trim returns a string, that is the result of slicing string s, with all leading and trailing Unicode code points contained in cutset removed.