[message] clarify partial read behavior of Read() vs ReadByte() (#10719)

This commit updates and clarifies the behavior of `Message::ReadByte()`
and `Message::Read()` overloads regarding partial reads.

- `ReadByte()` will read the available bytes and return the actual
  number of bytes read if fewer bytes are available in the message
  than the requested read length. This behavior remains unchanged.
  The documentation is updated to emphasize this behavior.
- `Read()` methods return `kErrorParse` if the requested length cannot
  be read. This is the existing behavior which remains unchanged.
  Previously, `Read()` methods would still perform a partial read and
  populate the buffer/object with as many bytes that could be read,
  even in case of failure and returning `kErrorParse`. This behavior
  has been changed in this commit so the method will skip
  reading/copying bytes if the full length cannot be read. This
  aligns the documentation and behavior with how the `Read()` methods
  are used and intended to be used within the OT stack.

tests/unit/test_message.cpp

@@ -157,6 +157,32 @@ void TestMessage(void)
             VerifyOrQuit(!message->CompareBytes(offset, readBuffer, length));
             VerifyOrQuit(message->CompareBytes(offset, readBuffer, readLength));
         }
+
+        // Verify `Read()` behavior when requested read length goes beyond available bytes in the message.
+
+        for (uint16_t length = kMaxSize - offset + 1; length <= kMaxSize + 1; length++)
+        {
+            Error error;
+
+            memset(readBuffer, 0, sizeof(readBuffer));
+
+            error = message->Read(offset, readBuffer, length);
+
+            if (length < kMaxSize - offset)
+            {
+                uint16_t readLength = kMaxSize - offset;
+
+                SuccessOrQuit(error);
+                VerifyOrQuit(memcmp(readBuffer, &writeBuffer[offset], readLength) == 0);
+                VerifyOrQuit(memcmp(&readBuffer[readLength], zeroBuffer, kMaxSize - readLength) == 0,
+                             "read after length");
+            }
+            else
+            {
+                VerifyOrQuit(error == kErrorParse);
+                VerifyOrQuit(memcmp(readBuffer, zeroBuffer, sizeof(readBuffer)) == 0, "Read() updated buffer on error");
+            }
+        }
     }
 
     VerifyOrQuit(message->GetLength() == kMaxSize);