Improve documentation of int

(cherry picked from commit 0f3197501e3420b7af212c47f184adf0781d7ec0)

1 files changed, 88 insertions, 95 deletions

diff --git a/doc/classes/int.xml b/doc/classes/int.xml
index 93fc8386c6..d5cb60e58d 100644
--- a/doc/classes/int.xml
+++ b/doc/classes/int.xml
@@ -1,40 +1,38 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="int" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Integer built-in type.
+		Built-in integer Variant type.
 	</brief_description>
 	<description>
-		Signed 64-bit integer type.
-		It can take values in the interval [code][-2^63, 2^63 - 1][/code], i.e. [code][-9223372036854775808, 9223372036854775807][/code]. Exceeding those bounds will wrap around.
-		[int] is a [Variant] type, and will thus be used when assigning an integer value to a [Variant]. It can also be enforced with the [code]: int[/code] type hint.
+		Signed 64-bit integer type. This means that it can take values from [code]-2^63[/code] to [code]2^63 - 1[/code], i.e. from [code]-9223372036854775808[/code] to [code]9223372036854775807[/code]. When it exceeds these bounds, it will wrap around.
+		[int]s can be automatically converted to [float]s when necessary, for example when passing them as arguments in functions. The [float] will be as close to the original integer as possible.
+		Likewise, [float]s can be automatically converted into [int]s. This will truncate the [float], discarding anything after the floating point.
+		[b]Note:[/b] In a boolean context, an [int] will evaluate to [code]false[/code] if it equals [code]0[/code], and to [code]true[/code] otherwise.
 		[codeblocks]
 		[gdscript]
-		var my_variant = 0 # int, value 0.
-		my_variant += 4.2 # float, value 4.2.
-		var my_int: int = 1 # int, value 1.
-		my_int = 4.2 # int, value 4, the right value is implicitly cast to int.
-		my_int = int("6.7") # int, value 6, the String is explicitly cast with int.
-		var max_int = 9223372036854775807
-		print(max_int) # 9223372036854775807, OK.
-		max_int += 1
-		print(max_int) # -9223372036854775808, we overflowed and wrapped around.
+		var x: int = 1 # x is 1
+		x = 4.2 # x is 4, because 4.2 gets truncated
+		var max_int = 9223372036854775807 # Biggest value an int can store
+		max_int += 1 # max_int is -9223372036854775808, because it wrapped around
 		[/gdscript]
 		[csharp]
-		int myInt = (int)"6.7".ToFloat(); // int, value 6, the String is explicitly cast with int.
-		// We have to use `long` here, because GDSript's `int`
-		// is 64 bits long while C#'s `int` is only 32 bits.
-		long maxInt = 9223372036854775807;
-		GD.Print(maxInt); // 9223372036854775807, OK.
-		maxInt++;
-		GD.Print(maxInt); // -9223372036854775808, we overflowed and wrapped around.
+		int x = 1; // x is 1
+		x = 4.2; // x is 4, because 4.2 gets truncated
+		// We use long below, because GDScript's int is 64-bit while C#'s int is 32-bit.
+		long maxLong = 9223372036854775807; // Biggest value a long can store
+		maxLong++; // maxLong is now -9223372036854775808, because it wrapped around.
 
-		// Alternatively, if we used C#'s 32-bit `int` type, the maximum value is much smaller:
-		int halfInt = 2147483647;
-		GD.Print(halfInt); // 2147483647, OK.
-		halfInt++;
-		GD.Print(halfInt); // -2147483648, we overflowed and wrapped around.
+		// Alternatively with C#'s 32-bit int type, which has a smaller maximum value.
+		int maxInt = 2147483647; // Biggest value an int can store
+		maxInt++; // maxInt is now -2147483648, because it wrapped around
 		[/csharp]
 		[/codeblocks]
+		In GDScript, you can use the [code]0b[/code] literal for binary representation, the [code]0x[/code] literal for hexadecimal representation, and the [code]_[/code] symbol to separate long numbers and improve readability.
+		[codeblock]
+		var x = 0b1001 # x is 9
+		var y = 0xF5 # y is 245
+		var z = 10_000_000 # z is 10000000
+		[/codeblock]
 	</description>
 	<tutorials>
 	</tutorials>
@@ -42,7 +40,7 @@
 		<constructor name="int">
 			<return type="int" />
 			<description>
-				Constructs a default-initialized [int] set to [code]0[/code].
+				Constructs an [int] set to [code]0[/code].
 			</description>
 		</constructor>
 		<constructor name="int">
@@ -56,21 +54,21 @@
 			<return type="int" />
 			<param index="0" name="from" type="String" />
 			<description>
-				Converts a [String] to an [int], following the same rules as [method String.to_int].
+				Constructs a new [int] from a [String], following the same rules as [method String.to_int].
 			</description>
 		</constructor>
 		<constructor name="int">
 			<return type="int" />
 			<param index="0" name="from" type="bool" />
 			<description>
-				Cast a [bool] value to an integer value, [code]int(true)[/code] will be equals to 1 and [code]int(false)[/code] will be equals to 0.
+				Constructs a new [int] from a [bool]. [code]true[/code] is converted to [code]1[/code] and [code]false[/code] is converted to [code]0[/code].
 			</description>
 		</constructor>
 		<constructor name="int">
 			<return type="int" />
 			<param index="0" name="from" type="float" />
 			<description>
-				Cast a float value to an integer value, this method simply removes the number fractions (i.e. rounds [param from] towards zero), so for example [code]int(2.7)[/code] will be equals to 2, [code]int(0.1)[/code] will be equals to 0 and [code]int(-2.7)[/code] will be equals to -2. This operation is also called truncation.
+				Constructs a new [int] from a [float]. This will truncate the [float], discarding anything after the floating point.
 			</description>
 		</constructor>
 	</constructors>
@@ -79,25 +77,25 @@
 			<return type="bool" />
 			<param index="0" name="right" type="float" />
 			<description>
-				Returns [code]true[/code] if this [int] is not equivalent to the given [float].
+				Returns [code]true[/code] if the [int] is not equivalent to the [float].
 			</description>
 		</operator>
 		<operator name="operator !=">
 			<return type="bool" />
 			<param index="0" name="right" type="int" />
 			<description>
-				Returns [code]true[/code] if the integers are not equal.
+				Returns [code]true[/code] if the [int]s are not equal.
 			</description>
 		</operator>
 		<operator name="operator %">
 			<return type="int" />
 			<param index="0" name="right" type="int" />
 			<description>
-				Returns the remainder after dividing two integers. This operation uses truncated division, which is often not desired as it does not work well with negative numbers. Consider using [method @GlobalScope.posmod] instead if you want to handle negative numbers.
+				Returns the remainder after dividing two [int]s. Uses truncated division, which returns a negative number if the dividend is negative. If this is not desired, consider using [method @GlobalScope.posmod].
 				[codeblock]
-				print(5 % 2) # 1
-				print(12 % 4) # 0
-				print(-5 % 3) # -2
+				print(6 % 2) # Prints 0
+				print(11 % 4) # Prints 3
+				print(-5 % 3) # Prints -2
 				[/codeblock]
 			</description>
 		</operator>
@@ -105,17 +103,16 @@
 			<return type="int" />
 			<param index="0" name="right" type="int" />
 			<description>
-				Returns the result of bitwise [code]AND[/code] operation for two integers.
+				Performs the bitwise [code]AND[/code] operation.
 				[codeblock]
-				print(3 &amp; 1) # 1
-				print(11 &amp; 3) # 3
+				print(0b1100 &amp; 0b1010) # Prints 8 (binary 1000)
 				[/codeblock]
-				It's useful to retrieve binary flags from a variable.
+				This is useful for retrieving binary flags from a variable.
 				[codeblock]
-				var flags = 5
-				# Do something if the first bit is enabled.
-				if flags &amp; 1:
-				    do_stuff()
+				var flags = 0b101
+				# Check if the first or second bit are enabled.
+				if flags &amp; 0b011:
+				    do_stuff() # This line will run.
 				[/codeblock]
 			</description>
 		</operator>
@@ -123,23 +120,23 @@
 			<return type="Color" />
 			<param index="0" name="right" type="Color" />
 			<description>
-				Multiplies each component of the [Color] by the given [int].
+				Multiplies each component of the [Color] by the [int].
 			</description>
 		</operator>
 		<operator name="operator *">
 			<return type="Quaternion" />
 			<param index="0" name="right" type="Quaternion" />
 			<description>
-				Multiplies each component of the [Quaternion] by the given [int]. This operation is not meaningful on its own, but it can be used as a part of a larger expression.
+				Multiplies each component of the [Quaternion] by the [int]. This operation is not meaningful on its own, but it can be used as a part of a larger expression.
 			</description>
 		</operator>
 		<operator name="operator *">
 			<return type="Vector2" />
 			<param index="0" name="right" type="Vector2" />
 			<description>
-				Multiplies each component of the [Vector2] by the given [int].
+				Multiplies each component of the [Vector2] by the [int].
 				[codeblock]
-				print(2 * Vector2(1, 1)) # Vector2(2, 2)
+				print(2 * Vector2(1, 4)) # Prints (2, 8)
 				[/codeblock]
 			</description>
 		</operator>
@@ -147,49 +144,49 @@
 			<return type="Vector2i" />
 			<param index="0" name="right" type="Vector2i" />
 			<description>
-				Multiplies each component of the [Vector2i] by the given [int].
+				Multiplies each component of the [Vector2i] by the [int].
 			</description>
 		</operator>
 		<operator name="operator *">
 			<return type="Vector3" />
 			<param index="0" name="right" type="Vector3" />
 			<description>
-				Multiplies each component of the [Vector3] by the given [int].
+				Multiplies each component of the [Vector3] by the [int].
 			</description>
 		</operator>
 		<operator name="operator *">
 			<return type="Vector3i" />
 			<param index="0" name="right" type="Vector3i" />
 			<description>
-				Multiplies each component of the [Vector3i] by the given [int].
+				Multiplies each component of the [Vector3i] by the [int].
 			</description>
 		</operator>
 		<operator name="operator *">
 			<return type="Vector4" />
 			<param index="0" name="right" type="Vector4" />
 			<description>
-				Multiplies each component of the [Vector4] by the given [int].
+				Multiplies each component of the [Vector4] by the [int].
 			</description>
 		</operator>
 		<operator name="operator *">
 			<return type="Vector4i" />
 			<param index="0" name="right" type="Vector4i" />
 			<description>
-				Multiplies each component of the [Vector4i] by the given [int].
+				Multiplies each component of the [Vector4i] by the [int].
 			</description>
 		</operator>
 		<operator name="operator *">
 			<return type="float" />
 			<param index="0" name="right" type="float" />
 			<description>
-				Multiplies an [int] and a [float]. The result is a [float].
+				Multiplies the [float] by the [int]. The result is a [float].
 			</description>
 		</operator>
 		<operator name="operator *">
 			<return type="int" />
 			<param index="0" name="right" type="int" />
 			<description>
-				Multiplies two [int]s.
+				Multiplies the two [int]s.
 			</description>
 		</operator>
 		<operator name="operator **">
@@ -198,7 +195,7 @@
 			<description>
 				Raises an [int] to a power of a [float]. The result is a [float].
 				[codeblock]
-				print(8**0.25) # 1.68179283050743
+				print(2 ** 0.5) # Prints 1.4142135623731
 				[/codeblock]
 			</description>
 		</operator>
@@ -206,9 +203,9 @@
 			<return type="int" />
 			<param index="0" name="right" type="int" />
 			<description>
-				Raises an [int] to a power of a [int].
+				Raises the left [int] to a power of the right [int].
 				[codeblock]
-				print(5**5) # 3125
+				print(3 ** 4) # Prints 81
 				[/codeblock]
 			</description>
 		</operator>
@@ -216,37 +213,37 @@
 			<return type="float" />
 			<param index="0" name="right" type="float" />
 			<description>
-				Adds an [int] and a [float]. The result is a [float].
+				Adds the [int] and the [float]. The result is a [float].
 			</description>
 		</operator>
 		<operator name="operator +">
 			<return type="int" />
 			<param index="0" name="right" type="int" />
 			<description>
-				Adds two integers.
+				Adds the two [int]s.
 			</description>
 		</operator>
 		<operator name="operator -">
 			<return type="float" />
 			<param index="0" name="right" type="float" />
 			<description>
-				Subtracts a [float] from an [int]. The result is a [float].
+				Subtracts the [float] from the [int]. The result is a [float].
 			</description>
 		</operator>
 		<operator name="operator -">
 			<return type="int" />
 			<param index="0" name="right" type="int" />
 			<description>
-				Subtracts two integers.
+				Subtracts the two [int]s.
 			</description>
 		</operator>
 		<operator name="operator /">
 			<return type="float" />
 			<param index="0" name="right" type="float" />
 			<description>
-				Divides an [int] by a [float]. The result is a [float].
+				Divides the [int] by the [float]. The result is a [float].
 				[codeblock]
-				print(10 / 3.0) # 3.333...
+				print(10 / 3.0) # Prints 3.33333333333333
 				[/codeblock]
 			</description>
 		</operator>
@@ -254,10 +251,10 @@
 			<return type="int" />
 			<param index="0" name="right" type="int" />
 			<description>
-				Divides two integers. The decimal part of the result is discarded (truncated).
+				Divides the two [int]s. The result is an [int]. This will truncate the [float], discarding anything after the floating point.
 				[codeblock]
-				print(10 / 2) # 5
-				print(10 / 3) # 3
+				print(6 / 2) # Prints 3
+				print(5 / 3) # Prints 1
 				[/codeblock]
 			</description>
 		</operator>
@@ -265,24 +262,24 @@
 			<return type="bool" />
 			<param index="0" name="right" type="float" />
 			<description>
-				Returns [code]true[/code] if this [int] is less than the given [float].
+				Returns [code]true[/code] if the [int] is less than the [float].
 			</description>
 		</operator>
 		<operator name="operator &lt;">
 			<return type="bool" />
 			<param index="0" name="right" type="int" />
 			<description>
-				Returns [code]true[/code] if the left integer is less than the right one.
+				Returns [code]true[/code] if the left [int] is less than the right [int].
 			</description>
 		</operator>
 		<operator name="operator &lt;&lt;">
 			<return type="int" />
 			<param index="0" name="right" type="int" />
 			<description>
-				Performs bitwise shift left operation on the integer. Effectively the same as multiplying by a power of 2.
+				Performs the bitwise shift left operation. Effectively the same as multiplying by a power of 2.
 				[codeblock]
-				print(10 &lt;&lt; 1) # 20
-				print(10 &lt;&lt; 4) # 160
+				print(0b1010 &lt;&lt; 1) # Prints 20 (binary 10100)
+				print(0b1010 &lt;&lt; 3) # Prints 80 (binary 1010000)
 				[/codeblock]
 			</description>
 		</operator>
@@ -290,66 +287,66 @@
 			<return type="bool" />
 			<param index="0" name="right" type="float" />
 			<description>
-				Returns [code]true[/code] if this [int] is less than or equal to the given [float].
+				Returns [code]true[/code] if the [int] is less than or equal to the [float].
 			</description>
 		</operator>
 		<operator name="operator &lt;=">
 			<return type="bool" />
 			<param index="0" name="right" type="int" />
 			<description>
-				Returns [code]true[/code] if the left integer is less than or equal to the right one.
+				Returns [code]true[/code] if the left [int] is less than or equal to the right [int].
 			</description>
 		</operator>
 		<operator name="operator ==">
 			<return type="bool" />
 			<param index="0" name="right" type="float" />
 			<description>
-				Returns [code]true[/code] if the integer is equal to the given [float].
+				Returns [code]true[/code] if the [int] is equal to the [float].
 			</description>
 		</operator>
 		<operator name="operator ==">
 			<return type="bool" />
 			<param index="0" name="right" type="int" />
 			<description>
-				Returns [code]true[/code] if both integers are equal.
+				Returns [code]true[/code] if the two [int]s are equal.
 			</description>
 		</operator>
 		<operator name="operator &gt;">
 			<return type="bool" />
 			<param index="0" name="right" type="float" />
 			<description>
-				Returns [code]true[/code] if this [int] is greater than the given [float].
+				Returns [code]true[/code] if the [int] is greater than the [float].
 			</description>
 		</operator>
 		<operator name="operator &gt;">
 			<return type="bool" />
 			<param index="0" name="right" type="int" />
 			<description>
-				Returns [code]true[/code] if the left integer is greater than the right one.
+				Returns [code]true[/code] if the left [int] is greater than the right [int].
 			</description>
 		</operator>
 		<operator name="operator &gt;=">
 			<return type="bool" />
 			<param index="0" name="right" type="float" />
 			<description>
-				Returns [code]true[/code] if this [int] is greater than or equal to the given [float].
+				Returns [code]true[/code] if the [int] is greater than or equal to the [float].
 			</description>
 		</operator>
 		<operator name="operator &gt;=">
 			<return type="bool" />
 			<param index="0" name="right" type="int" />
 			<description>
-				Returns [code]true[/code] if the left integer is greater than or equal to the right one.
+				Returns [code]true[/code] if the left [int] is greater than or equal to the right [int].
 			</description>
 		</operator>
 		<operator name="operator &gt;&gt;">
 			<return type="int" />
 			<param index="0" name="right" type="int" />
 			<description>
-				Performs bitwise shift right operation on the integer. Effectively the same as dividing by a power of 2.
+				Performs the bitwise shift right operation. Effectively the same as dividing by a power of 2.
 				[codeblock]
-				print(10 &gt;&gt; 1) # 5
-				print(10 &gt;&gt; 2) # 2
+				print(0b1010 &gt;&gt; 1) # Prints 5 (binary 101)
+				print(0b1010 &gt;&gt; 2) # Prints 2 (binary 10)
 				[/codeblock]
 			</description>
 		</operator>
@@ -357,10 +354,9 @@
 			<return type="int" />
 			<param index="0" name="right" type="int" />
 			<description>
-				Returns the result of bitwise [code]XOR[/code] operation for two integers.
+				Performs the bitwise [code]XOR[/code] operation.
 				[codeblock]
-				print(5 ^ 1) # 4
-				print(4 ^ 7) # 3
+				print(0b1100 ^ 0b1010) # Prints 6 (binary 110)
 				[/codeblock]
 			</description>
 		</operator>
@@ -380,27 +376,24 @@
 			<return type="int" />
 			<param index="0" name="right" type="int" />
 			<description>
-				Returns the result of bitwise [code]OR[/code] operation for two integers.
+				Performs the bitwise [code]OR[/code] operation.
 				[codeblock]
-				print(2 | 4) # 6
-				print(1 | 3) # 3
+				print(0b1100 | 0b1010) # Prints 14 (binary 1110)
 				[/codeblock]
-				It's useful to store binary flags in a variable.
+				This is useful for storing binary flags in a variable.
 				[codeblock]
 				var flags = 0
-				# Turn first and third bit on.
-				flags |= 1
-				flags |= 4
+				flags |= 0b101 # Turn the first and third bits on.
 				[/codeblock]
 			</description>
 		</operator>
 		<operator name="operator ~">
 			<return type="int" />
 			<description>
-				Returns the result of bitwise [code]NOT[/code] operation for the integer. It's effectively equal to [code]-int + 1[/code].
+				Performs the bitwise [code]NOT[/code] operation on the [int]. Due to [url=https://en.wikipedia.org/wiki/Two%27s_complement/]2's complement[/url], it's effectively equal to [code]-(int + 1)[/code].
 				[codeblock]
-				print(~4) # -3
-				print(~7) # -6
+				print(~4) # Prints -5
+				print(~(-7)) # Prints 6
 				[/codeblock]
 			</description>
 		</operator>