encoding/base64: improve documentation on decoding to a short dst

[hhhapz]

As seen in the issue #50117, providing a dst slice that is valid in size (a multiple of what base64 data decode into) but not large enough for the entire source base64 causes a panic. I was surprised to see that it wasn't documented, and from the function comment:

It writes at most Encoding.DecodedLen(len(src)) bytes to dst and returns the number of bytes written.

A reader would assume that this would therefore decode at most input, (implying a shorter amount would also be possible). I understand that this is not an intended use case, however it should be more explicitly documented that a shorter dst will panic.

[gabyhelp]

Related Issues and Documentation

• encoding/base64: Decode shouldn't panic when destination buffer is insufficient #63278 (closed)
• encoding/base64 Decode panics if given too short dst #54532 (closed)
• encoding/base64: Decode panics on short dst #50117 (closed)
• encoding/base64: document if (*Encoding).Decode arguments may overlap #56070

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[gopherbot]

Change https://go.dev/cl/607499 mentions this issue: encoding/base32, encoding/base64: document Decode to short buffer