How to correctly phrase documentation about test matchers accepting Go 1.23 iterator functions?

[TheDiveO]

Background: I'm currently working on making the Gomega matcher library iterator-aware as first-class citizens. That is, matchers working on "collection" types such as slice and map will then accept iterator functions and act accordingly. As I also work on updating the matcher documentation I'm struggling with terminology/wording. Please keep in mind that the matcher documentation needs to be sweet and short, as there are repetitive mentioning of iterator handling appearing in multiple places.

To use a concrete example, BeEmpty() currently pre-iterator is described as follows:

[...] succeeds if ACTUAL is, in fact, empty. ACTUAL must be of type string, array, map, chan, or slice. It is an error for it to have any other type.

Here, I want now to add that ACTUAL additionally can be an iterator in a hopefully concise, yet compact way. Please note that we don't want to support any range-able value here, just iterators.

Now, does the term "iterator" always refer to a function, and in particular, to "a function that passes successive elements of a sequence to a callback function"? [package iter, section Iterators]

How can I guide devs new to Go's iterator pattern to quickly grasp that ACTUAL can be a function that is "assignable to" (i.e., "AssignableTo" in reflect speak) iter.Seq and/or  iter.Seq2 .  Is the following phrasing (bold to emphasize the new part) acceptable? Can this be improved (without singing an opera)?

[...] succeeds if ACTUAL is, in fact, empty. ACTUAL must be of type string, array, map, chan, or slice. Starting with Go 1.23, ACTUAL can be also an iterator function with an iter.Seq or  iter.Seq2-like signature . It is an error for it to have any other type.

[Axel Wagner]

I would either just write "an iterator", or "a function assignable to iter.Seq or iter.Seq2". Assignability is a well-defined term that seems more precise than talking about a signature being "like" something.

Out of curiosity: From the documentation you quote, it seems that if I do `type MyString string`, that would not be allowed? Because that seems a strange restriction to me - but it also seems strange to me to go out of your way to include all the nuance when it comes to iter.Seq, but then not put that nuance into the documentation of any of the other types. Like, you say "or `slice`", but `slice` is not a type, so presumably that means "any slice type"? Or does it mean something like "`[]T`, where `T` is any type" (so in particular not defined types). Or does it mean "a slice of some further constrained type"? Clearly there is ambiguity in the existing docs. So just saying "it can also be an iterator" or "it can also be iter.Seq" should be acceptable?

--
You received this message because you are subscribed to the Google Groups "golang-nuts" group.
To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/golang-nuts/d736f3a4-6a3d-4925-9f42-3e4189393cc1n%40googlegroups.com.

[TheDiveO]

  I was asking for the rabbit, erm Gopher, hole, so there's a lot for me to learn here! Please be patient with me, I'm trying my best, but the the finer points in Go for me still escape much farther than the heap...

On Thursday, November 14, 2024 at 10:50:58 AM UTC+1 Axel Wagner wrote:

I would either just write "an iterator", or "a function assignable to iter.Seq or iter.Seq2". Assignability is a well-defined term that seems more precise than talking about a signature being "like" something.

Ah, thank you very much! I'll probably opt for the latter to put the specific iterator types right before a dev's eyes. Or alternatively put this in the beginning of the "Collections" subsection explaining it for once and all, and then just going for your short "an iterator".

 

Out of curiosity: From the documentation you quote, it seems that if I do `type MyString string`, that would not be allowed? Because that seems a strange restriction to me - but it also seems strange to me to go out of your way to include all the nuance when it comes to iter.Seq, but then not put that nuance into the documentation of any of the other types.

You are right (also with your curiosity), a value of type MyString is also accepted; how would you phrase that part, dropping the "of type" in the sentence "ACTUAL must be ..."? Does this sentence need more fixing? Or a bigger overhaul?

 

Like, you say "or `slice`", but `slice` is not a type, so presumably that means "any slice type"? Or does it mean something like "`[]T`, where `T` is any type" (so in particular not defined types). Or does it mean "a slice of some further constrained type"? Clearly there is ambiguity in the existing docs.

Expecting devs to have read "A Tour of Go"'s part about Slices, this would be "The type []T is a slice with elements of type T." Would the aforementioned dropping of "of type" also solve this?