diff --git a/doc/classes/File.xml b/doc/classes/File.xml
index 735bf69aa0a..dbba0267460 100644
--- a/doc/classes/File.xml
+++ b/doc/classes/File.xml
@@ -54,28 +54,28 @@
- Returns the next 16 bits from the file as an integer.
+ Returns the next 16 bits from the file as an integer. See [method store_16] for details on what values can be stored and retrieved this way.
- Returns the next 32 bits from the file as an integer.
+ Returns the next 32 bits from the file as an integer. See [method store_32] for details on what values can be stored and retrieved this way.
- Returns the next 64 bits from the file as an integer.
+ Returns the next 64 bits from the file as an integer. See [method store_64] for details on what values can be stored and retrieved this way.
- Returns the next 8 bits from the file as an integer.
+ Returns the next 8 bits from the file as an integer. See [method store_8] for details on what values can be stored and retrieved this way.
@@ -297,7 +297,26 @@
Stores an integer as 16 bits in the file.
- [b]Note:[/b] The [code]value[/code] should lie in the interval [code][0, 2^16 - 1][/code].
+ [b]Note:[/b] The [code]value[/code] should lie in the interval [code][0, 2^16 - 1][/code]. Any other value will overflow and wrap around.
+ To store a signed integer, use [method store_64] or store a signed integer from the interval [code][-2^15, 2^15 - 1][/code] (i.e. keeping one bit for the signedness) and compute its sign manually when reading. For example:
+ [codeblock]
+ const MAX_15B = 1 << 15
+ const MAX_16B = 1 << 16
+
+ func unsigned16_to_signed(unsigned):
+ return (unsigned + MAX_15B) % MAX_16B - MAX_15B
+
+ func _ready():
+ var f = File.new()
+ f.open("user://file.dat", File.WRITE_READ)
+ f.store_16(-42) # This wraps around and stores 65494 (2^16 - 42).
+ f.store_16(121) # In bounds, will store 121.
+ f.seek(0) # Go back to start to read the stored value.
+ var read1 = f.get_16() # 65494
+ var read2 = f.get_16() # 121
+ var converted1 = unsigned16_to_signed(read1) # -42
+ var converted2 = unsigned16_to_signed(read2) # 121
+ [/codeblock]
@@ -307,7 +326,8 @@
Stores an integer as 32 bits in the file.
- [b]Note:[/b] The [code]value[/code] should lie in the interval [code][0, 2^32 - 1][/code].
+ [b]Note:[/b] The [code]value[/code] should lie in the interval [code][0, 2^32 - 1][/code]. Any other value will overflow and wrap around.
+ To store a signed integer, use [method store_64], or convert it manually (see [method store_16] for an example).
@@ -327,7 +347,8 @@
Stores an integer as 8 bits in the file.
- [b]Note:[/b] The [code]value[/code] should lie in the interval [code][0, 255][/code].
+ [b]Note:[/b] The [code]value[/code] should lie in the interval [code][0, 255][/code]. Any other value will overflow and wrap around.
+ To store a signed integer, use [method store_64], or convert it manually (see [method store_16] for an example).