assert: add comment that explains the MaxScanTokenSize handling logic

assert/assertions.go

@@ -302,6 +302,12 @@ func indentMessageLines(message string, longestLabelLen int) string {
 	outBuf := new(bytes.Buffer)
 
 	msgScanner := bufio.NewScanner(strings.NewReader(message))
+
+	// a buffer is set manually to store the tokenization of the message string
+	// so that we can re-use the same buffer for each line of the message without
+	// any additional allocations. We set the buffer length to 1 more than the
+	// length of the message to avoid exceeding the default MaxScanTokenSize
+	// while scanning lines. This CAN happen. Refer to issue #1525
 	msgScanner.Buffer([]byte{}, len(message)+1)
 
 	first := true