Clarify description on ds_map_add() to make the difference between the function and the $ accessor clear when overwriting existing keys

[Grisgram]

Description

Hey there,

The manual for ds_map_add contains confusing text, which forced me to try out, what really happens.
Would be great, if you could state the difference between ds_map_add and access through accessor clearly.

Manual says, ds_map_add can return false, if the key exists. This is correct.
Then you show this code examples:

ds_map_add(map, 5, undefined);
ds_map_add(map, "level", 1);
ds_map_add(map, 89.6, "hello world");
ds_map_add(map, 5, buffer_get_address(buff));

but you mention with no word, that the last line will fail and the function will return false here.

IN ADDITION to that, you added a part for the accessors, when they were released, with almost the same samples,

map[? 5] = undefined;
map[? "level"] = 1;
map[? 89.6] = "hello world";
map[? 5] = buffer_get_address(buff);

And again, you mention not with a single word, that in this case the last line will succeed!

This is mega-confusing.

I wrote these few testing lines to prove:

test = ds_map_create();
test[? "hallo"] = "welt";
test[? "hallo"] = "world";
show_debug_message($"--- {test[?"hallo"]}");vlog
ds_map_destroy(test);

test = ds_map_create();
ds_map_add(test, "hallo", "welt");
ds_map_add(test, "hallo", "world");
show_debug_message($"--- {test[?"hallo"]}");
ds_map_destroy(test);

And indeed, the first block prints

--- world

to the log and the second block prints

--- welt

as this block uses ds_map_add instead of the accessors.

You need to make this clear in the manual!

thanks for reading,
kind regards
Gris

Steps To Reproduce

• run the code shown above and adapt the manual accordingly

0bd05f22-3783-4e2e-9c0a-879a3d8a9445