Make it clear that chunks() and chunks_mut() can be called on their own chunks

[urschrei]

I know that it's implied by the docs, but it wasn't immediately obvious to me that the chunks returned by chunks() and chunks_mut() can (I'm avoiding use of the term "recursive" here) have chunks or chunks_mut called on themselves (playground).
Is there any interest in a PR that makes this explicit? It seems that especially when working with threads and work-stealing, this is something that users want to do.

[bluss]

Is it enough to stress that each chunk is itself a slice (or mutable slice)?

[urschrei]

Hm. What would be the distinction between stressing it and showing it? In theory, it should be obvious that because the chunk is a slice, you can call chunks() on it. At the same time, it depends on the intended audience; For the beginner, it means that there's no need to go off to the playpen or ask a question (which may or may not be a good thing, depending on your point of view).

Either option is an improvement, and I'm probably over-thinking the whole thing now.

[steveklabnik]

In general, API docs usually are written for an intermediate/advanced user: we don't generally mention "oh and because this has a return type of foo you can call these other things on it." Where does this stop and end?

[urschrei]

we don't generally mention "oh and because this has a return type of foo you can call these other things on it."

Fair point. But what about explicitly stating that the functions return slices, as opposed to "an iterator"?

[sfackler]

It does return an iterator - an iterator over slices.

[urschrei]

It does return an iterator - an iterator over slices.

Undeniably true, but I don't think it's clear; The docs say "an iterator over size / chunk_size elements of the slice".

[Thiez]

I'm not sure one would be able to use chunks and chunks_mut correctly without understanding that they yield slices. Once you understand that you can use chunks to divide a slice into more slices, surely it makes sense that one can divide those slices in yet more slices, In much the same way that one can add two numbers and use the result for further addition.

[bluss]

Yes we should clarify the docs to say it returns an iterator whose elements are slices.