Manual Content: buffer_read() page does not explain the requirement for moving the seek position first

[YYDan]

Description

The page for buffer_read() does not really impress/clarify just how important the seek position is before you start reading from the buffer, and accordingly the sample lower down on the page does not really show anything useful.

Currently, the only mention to the seek position comes at the very top of the page and so is very easy to skim past:

And the sample is just one line:

Expected Change

We extend the wording at the top to clarify the importance of the seek position:

This function can be used to read data from a previously-created buffer. Be aware that it will only read the contents starting from at the buffer's current seek position, so you must ensure this is set correctly before calling the function - otherwise, you will get either incorrect results or nothing at all being returned,

And we make the sample code block an end-to-end example which shows the need for controlling the seek position:

testBuffer = buffer_create(10240, buffer_grow, 1);

//buffer_seek(testBuffer, buffer_seek_start, 0);   // This one is optional, as the buffer has only just been created, so the seek IS 0 already
buffer_write(testBuffer, buffer_string, "Hello World");

buffer_seek(testBuffer, buffer_seek_start, 0);    // This line is required, as we have since written data to the buffer and so moved the seek
myResult = buffer_read(testBuffer, buffer_string);

show_debug_message("Result = " + myResult);

ManualBufferExample.zip

Manual Link

https://manual.gamemaker.io/monthly/en/#t=GameMaker_Language%2FGML_Reference%2FBuffers%2Fbuffer_read.htm