Go convention is that for a function or method returning (T, error), T is not to be considered if the error != nil unless otherwise documented, and we try to only document the exceptions so the documentation doesn't turn into stutter everywhere.

But considering that io.Reader is such an exception and io.ByteReader looks similar in name, I could see the argument for calling out the behavior here explicitly.

But we wouldn't document that the byte must be 0. Just that it's meaningless if error != nil.

That sounds reasonable, since callers can't assume anything about the return value in that case. Is it okay to submit a CL?

Go for it. Note that document CLs are some of the pickiest reviews, so it might take a few rounds of wordsmithing until it matches Go doc style.

FYI, this is a duplicate of #11308.

In my original CL, it originally worded it as "An error is reported only if no byte is available.", which I personally still prefer.

See http://golang.org/cl/15256/

Although CL mentioned in #11308 is well worded, this issue tries to make more of an implication. I think any possible confusion arises out of the fact that callers care about the value of the byte, not the error. Taking inspiration from math/big, one possibility is "The returned byte is valid but not defined if an error is reported."

CL https://golang.org/cl/46950 mentions this issue.