From 575a1dc9cff82e6f8b7c3f0f753924b52978ff92 Mon Sep 17 00:00:00 2001
From: James Westman <flyingpimonster@gmail.com>
Date: Tue, 17 Dec 2019 16:24:54 -0600
Subject: [PATCH] Docs: OptionButton

Complete the documentation and make some existing descriptions a bit
clearer.

Co-Authored-By: Hugo Locurcio <hugo.locurcio@hugo.pro>
---
 doc/classes/OptionButton.xml | 25 +++++++++++++++++--------
 1 file changed, 17 insertions(+), 8 deletions(-)

diff --git a/doc/classes/OptionButton.xml b/doc/classes/OptionButton.xml
index b3f1359e694..0debb988ce6 100644
--- a/doc/classes/OptionButton.xml
+++ b/doc/classes/OptionButton.xml
@@ -19,7 +19,7 @@
 			<argument index="2" name="id" type="int" default="-1">
 			</argument>
 			<description>
-				Adds an item, with a [code]texture[/code] icon, text [code]label[/code] and (optionally) [code]id[/code]. If no [code]id[/code] is passed, [code]id[/code] becomes the item index. New items are appended at the end.
+				Adds an item, with a [code]texture[/code] icon, text [code]label[/code] and (optionally) [code]id[/code]. If no [code]id[/code] is passed, the item index will be used as the item's ID. New items are appended at the end.
 			</description>
 		</method>
 		<method name="add_item">
@@ -30,7 +30,7 @@
 			<argument index="1" name="id" type="int" default="-1">
 			</argument>
 			<description>
-				Adds an item, with text [code]label[/code] and (optionally) [code]id[/code]. If no [code]id[/code] is passed, [code]id[/code] becomes the item index. New items are appended at the end.
+				Adds an item, with text [code]label[/code] and (optionally) [code]id[/code]. If no [code]id[/code] is passed, the item index will be used as the item's ID. New items are appended at the end.
 			</description>
 		</method>
 		<method name="add_separator">
@@ -44,14 +44,14 @@
 			<return type="void">
 			</return>
 			<description>
-				Clear all the items in the [OptionButton].
+				Clears all the items in the [OptionButton].
 			</description>
 		</method>
 		<method name="get_item_count" qualifiers="const">
 			<return type="int">
 			</return>
 			<description>
-				Returns the amount of items in the OptionButton.
+				Returns the amount of items in the OptionButton, including separators.
 			</description>
 		</method>
 		<method name="get_item_icon" qualifiers="const">
@@ -87,6 +87,7 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+				Retrieves the metadata of an item. Metadata may be any type and can be used to store extra information about an item, such as an external string ID.
 			</description>
 		</method>
 		<method name="get_item_text" qualifiers="const">
@@ -109,12 +110,14 @@
 			<return type="int">
 			</return>
 			<description>
+				Returns the ID of the selected item, or [code]0[/code] if no item is selected.
 			</description>
 		</method>
 		<method name="get_selected_metadata" qualifiers="const">
 			<return type="Variant">
 			</return>
 			<description>
+				Gets the metadata of the selected item. Metadata for items can be set using [method set_item_metadata].
 			</description>
 		</method>
 		<method name="is_item_disabled" qualifiers="const">
@@ -123,6 +126,7 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+				Returns [code]true[/code] if the item at index [code]idx[/code] is disabled.
 			</description>
 		</method>
 		<method name="remove_item">
@@ -131,6 +135,7 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+				Removes the item at index [code]idx[/code].
 			</description>
 		</method>
 		<method name="select">
@@ -139,7 +144,7 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
-				Select an item by index and make it the current item.
+				Selects an item by index and makes it the current item. This will work even if the item is disabled.
 			</description>
 		</method>
 		<method name="set_item_disabled">
@@ -150,6 +155,8 @@
 			<argument index="1" name="disabled" type="bool">
 			</argument>
 			<description>
+				Sets whether the item at index [code]idx[/code] is disabled.
+				Disabled items are drawn differently in the dropdown and are not selectable by the user. If the current selected item is set as disabled, it will remain selected.
 			</description>
 		</method>
 		<method name="set_item_icon">
@@ -160,7 +167,7 @@
 			<argument index="1" name="texture" type="Texture">
 			</argument>
 			<description>
-				Sets the icon of an item at index [code]idx[/code].
+				Sets the icon of the item at index [code]idx[/code].
 			</description>
 		</method>
 		<method name="set_item_id">
@@ -171,7 +178,7 @@
 			<argument index="1" name="id" type="int">
 			</argument>
 			<description>
-				Sets the ID of an item at index [code]idx[/code].
+				Sets the ID of the item at index [code]idx[/code].
 			</description>
 		</method>
 		<method name="set_item_metadata">
@@ -182,6 +189,7 @@
 			<argument index="1" name="metadata" type="Variant">
 			</argument>
 			<description>
+				Sets the metadata of an item. Metadata may be of any type and can be used to store extra information about an item, such as an external string ID.
 			</description>
 		</method>
 		<method name="set_item_text">
@@ -192,7 +200,7 @@
 			<argument index="1" name="text" type="String">
 			</argument>
 			<description>
-				Sets the text of an item at index [code]idx[/code].
+				Sets the text of the item at index [code]idx[/code].
 			</description>
 		</method>
 	</methods>
@@ -200,6 +208,7 @@
 		<member name="action_mode" type="int" setter="set_action_mode" getter="get_action_mode" override="true" enum="BaseButton.ActionMode" default="0" />
 		<member name="align" type="int" setter="set_text_align" getter="get_text_align" override="true" enum="Button.TextAlign" default="0" />
 		<member name="selected" type="int" setter="_select_int" getter="get_selected" default="-1">
+			The index of the currently selected item, or [code]-1[/code] if no item is selected.
 		</member>
 		<member name="toggle_mode" type="bool" setter="set_toggle_mode" getter="is_toggle_mode" override="true" default="true" />
 	</members>