From 5a1f94ba47e06ad873c3d80385a9440169015bd7 Mon Sep 17 00:00:00 2001
From: Hugo Locurcio <hugo.locurcio@hugo.pro>
Date: Thu, 11 Jun 2020 19:53:55 +0200
Subject: [PATCH] Document the `in` operator in String, Array and Dictionary
 classes

This also clarifies the `in` operator behavior in Object.

(cherry picked from commit 7f01f68226c3aa32a372afba3b254402a9448830)
---
 doc/classes/Array.xml      | 10 ++++++++--
 doc/classes/Dictionary.xml |  7 +++++++
 doc/classes/Object.xml     |  1 +
 doc/classes/String.xml     | 14 ++++++++++----
 4 files changed, 26 insertions(+), 6 deletions(-)

diff --git a/doc/classes/Array.xml b/doc/classes/Array.xml
index ed445896dc2..54cd4109cc0 100644
--- a/doc/classes/Array.xml
+++ b/doc/classes/Array.xml
@@ -176,7 +176,7 @@
 			<argument index="1" name="from" type="int" default="0">
 			</argument>
 			<description>
-				Searches the array for a value and returns its index or -1 if not found. Optionally, the initial search index can be passed.
+				Searches the array for a value and returns its index or [code]-1[/code] if not found. Optionally, the initial search index can be passed.
 			</description>
 		</method>
 		<method name="find_last">
@@ -185,7 +185,7 @@
 			<argument index="0" name="value" type="Variant">
 			</argument>
 			<description>
-				Searches the array in reverse order for a value and returns its index or -1 if not found.
+				Searches the array in reverse order for a value and returns its index or [code]-1[/code] if not found.
 			</description>
 		</method>
 		<method name="front">
@@ -208,6 +208,12 @@
 				["inside", 7].has(7) == true
 				["inside", 7].has("7") == false
 				[/codeblock]
+				[b]Note:[/b] This is equivalent to using the [code]in[/code] operator as follows:
+				[codeblock]
+				# Will evaluate to `true`.
+				if 2 in [2, 4, 6, 8]:
+				    pass
+				[/codeblock]
 			</description>
 		</method>
 		<method name="hash">
diff --git a/doc/classes/Dictionary.xml b/doc/classes/Dictionary.xml
index 32a3ba89fe5..63cabbc44f8 100644
--- a/doc/classes/Dictionary.xml
+++ b/doc/classes/Dictionary.xml
@@ -124,6 +124,13 @@
 			</argument>
 			<description>
 				Returns [code]true[/code] if the dictionary has a given key.
+				[b]Note:[/b] This is equivalent to using the [code]in[/code] operator as follows:
+				[codeblock]
+				# Will evaluate to `true`.
+				if "godot" in {"godot": "engine"}:
+				    pass
+				[/codeblock]
+				This method (like the [code]in[/code] operator) will evaluate to [code]true[/code] as long as the key exists, even if the associated value is [code]null[/code].
 			</description>
 		</method>
 		<method name="has_all">
diff --git a/doc/classes/Object.xml b/doc/classes/Object.xml
index 4ee2b721e35..a6f11fea55d 100644
--- a/doc/classes/Object.xml
+++ b/doc/classes/Object.xml
@@ -15,6 +15,7 @@
 		print("position" in n) # Prints "True".
 		print("other_property" in n) # Prints "False".
 		[/codeblock]
+		The [code]in[/code] operator will evaluate to [code]true[/code] as long as the key exists, even if the value is [code]null[/code].
 		Objects also receive notifications. Notifications are a simple way to notify the object about different events, so they can all be handled together. See [method _notification].
 	</description>
 	<tutorials>
diff --git a/doc/classes/String.xml b/doc/classes/String.xml
index fd44ae5ca32..ab331a47d5c 100644
--- a/doc/classes/String.xml
+++ b/doc/classes/String.xml
@@ -338,7 +338,13 @@
 			<argument index="1" name="from" type="int" default="0">
 			</argument>
 			<description>
-				Finds the first occurrence of a substring. Returns the starting position of the substring or -1 if not found. Optionally, the initial search index can be passed.
+				Finds the first occurrence of a substring. Returns the starting position of the substring or [code]-1[/code] if not found. Optionally, the initial search index can be passed.
+				[b]Note:[/b] If you just want to know whether a string contains a substring, use the [code]in[/code] operator as follows:
+				[codeblock]
+				# Will evaluate to `false`.
+				if "i" in "team":
+				    pass
+				[/codeblock]
 			</description>
 		</method>
 		<method name="find_last">
@@ -347,7 +353,7 @@
 			<argument index="0" name="what" type="String">
 			</argument>
 			<description>
-				Finds the last occurrence of a substring. Returns the starting position of the substring or -1 if not found.
+				Finds the last occurrence of a substring. Returns the starting position of the substring or [code]-1[/code] if not found.
 			</description>
 		</method>
 		<method name="findn">
@@ -358,7 +364,7 @@
 			<argument index="1" name="from" type="int" default="0">
 			</argument>
 			<description>
-				Finds the first occurrence of a substring, ignoring case. Returns the starting position of the substring or -1 if not found. Optionally, the initial search index can be passed.
+				Finds the first occurrence of a substring, ignoring case. Returns the starting position of the substring or [code]-1[/code] if not found. Optionally, the initial search index can be passed.
 			</description>
 		</method>
 		<method name="format">
@@ -860,7 +866,7 @@
 			<argument index="1" name="len" type="int" default="-1">
 			</argument>
 			<description>
-				Returns part of the string from the position [code]from[/code] with length [code]len[/code]. Argument [code]len[/code] is optional and using -1 will return remaining characters from given position.
+				Returns part of the string from the position [code]from[/code] with length [code]len[/code]. Argument [code]len[/code] is optional and using [code]-1[/code] will return remaining characters from given position.
 			</description>
 		</method>
 		<method name="to_ascii">