Mock::with_chunked_body could use better documentation

[mstange]

Reading the documentation for with_chunked_body I wasn't immediately sure how the callback function is used. Is it called once per chunk? Or just once? What determines the size of the chunks?

I think the answers are: It's called just once. Every call to write* on the writer argument becomes one chunk. The callback function can sleep between the write calls in order to put delays between the chunks. The callback function can also return an error after any number of write calls in order to abort the response.

Should the type of the callback function be FnOnce rather than Fn to emphasize the fact that it's only called once?

[lipanski]

That is correct and, as you pointed out, you can sleep between writes to simulate delay between the chunks. I'll make a note to update the docs but PRs are also welcome 😉

[lipanski]

Addressed in #191

[mstange]

Thank you! One question still remains: Should it be FnOnce instead?

[lipanski]

Aside from semantics do you see any other benefits in using FnOnce? I'm hesitant to change this since it would be a slight breaking change.

[mstange]

It would allow users to consume values in the callback that get moved in from outside the callback. For example, you might have a Vec that you move into the callback and then consume it by calling into_iter(). This would not compile with the Fn bound.
There are probably more compelling examples but I couldn't think of any :)

It's also not a problem I have myself. I agree that it's probably not worth doing a breaking change just for this, but maybe something to look at when making other breaking changes.