From 011bf095166d88d560087bbf83d07567309c585f Mon Sep 17 00:00:00 2001
From: smoogipoo <smoogipoo@smgi.me>
Date: Fri, 8 Nov 2019 13:14:23 +0900
Subject: [PATCH] Add xmldocs and cleanup

---
 .../TestSceneStatefulMenuItem.cs              |  5 ++-
 .../UserInterface/StatefulMenuItem.cs         | 45 +++++++++++++++++++
 .../UserInterface/ThreeStateMenuItem.cs       | 45 +++++++++++++++++--
 .../Graphics/UserInterface/ToggleMenuItem.cs  | 14 ++++++
 4 files changed, 104 insertions(+), 5 deletions(-)

diff --git a/osu.Game.Tests/Visual/UserInterface/TestSceneStatefulMenuItem.cs b/osu.Game.Tests/Visual/UserInterface/TestSceneStatefulMenuItem.cs
index 00678a6ab4..d010abc862 100644
--- a/osu.Game.Tests/Visual/UserInterface/TestSceneStatefulMenuItem.cs
+++ b/osu.Game.Tests/Visual/UserInterface/TestSceneStatefulMenuItem.cs
@@ -74,9 +74,10 @@ namespace osu.Game.Tests.Visual.UserInterface
 
                     case TestStates.State3:
                         return FontAwesome.Solid.DiceThree;
-                }
 
-                return null;
+                    default:
+                        throw new ArgumentOutOfRangeException(nameof(state), state, null);
+                }
             }
         }
 
diff --git a/osu.Game/Graphics/UserInterface/StatefulMenuItem.cs b/osu.Game/Graphics/UserInterface/StatefulMenuItem.cs
index b5f9a3d635..0d7b36e51b 100644
--- a/osu.Game/Graphics/UserInterface/StatefulMenuItem.cs
+++ b/osu.Game/Graphics/UserInterface/StatefulMenuItem.cs
@@ -7,15 +7,34 @@ using osu.Framework.Graphics.Sprites;
 
 namespace osu.Game.Graphics.UserInterface
 {
+    /// <summary>
+    /// An <see cref="OsuMenuItem"/> which contains and displays a state.
+    /// </summary>
     public abstract class StatefulMenuItem : OsuMenuItem
     {
+        /// <summary>
+        /// The current state that should be displayed.
+        /// </summary>
         public readonly Bindable<object> State = new Bindable<object>();
 
+        /// <summary>
+        /// Creates a new <see cref="StatefulMenuItem"/>.
+        /// </summary>
+        /// <param name="text">The text to display.</param>
+        /// <param name="changeStateFunc">A function that mutates a state to another state after this <see cref="StatefulMenuItem"/> is pressed.</param>
+        /// <param name="type">The type of action which this <see cref="StatefulMenuItem"/> performs.</param>
         protected StatefulMenuItem(string text, Func<object, object> changeStateFunc, MenuItemType type = MenuItemType.Standard)
             : this(text, changeStateFunc, type, null)
         {
         }
 
+        /// <summary>
+        /// Creates a new <see cref="StatefulMenuItem"/>.
+        /// </summary>
+        /// <param name="text">The text to display.</param>
+        /// <param name="changeStateFunc">A function that mutates a state to another state after this <see cref="StatefulMenuItem"/> is pressed.</param>
+        /// <param name="type">The type of action which this <see cref="StatefulMenuItem"/> performs.</param>
+        /// <param name="action">A delegate to be invoked when this <see cref="StatefulMenuItem"/> is pressed.</param>
         protected StatefulMenuItem(string text, Func<object, object> changeStateFunc, MenuItemType type, Action<object> action)
             : base(text, type)
         {
@@ -26,19 +45,40 @@ namespace osu.Game.Graphics.UserInterface
             };
         }
 
+        /// <summary>
+        /// Retrieves the icon to be displayed for a state.
+        /// </summary>
+        /// <param name="state">The state to retrieve the relevant icon for.</param>
+        /// <returns>The icon to be displayed for <paramref name="state"/>.</returns>
         public abstract IconUsage? GetIconForState(object state);
     }
 
     public abstract class StatefulMenuItem<T> : StatefulMenuItem
         where T : struct
     {
+        /// <summary>
+        /// The current state that should be displayed.
+        /// </summary>
         public new readonly Bindable<T> State = new Bindable<T>();
 
+        /// <summary>
+        /// Creates a new <see cref="StatefulMenuItem"/>.
+        /// </summary>
+        /// <param name="text">The text to display.</param>
+        /// <param name="changeStateFunc">A function that mutates a state to another state after this <see cref="StatefulMenuItem"/> is pressed.</param>
+        /// <param name="type">The type of action which this <see cref="StatefulMenuItem"/> performs.</param>
         protected StatefulMenuItem(string text, Func<T, T> changeStateFunc, MenuItemType type = MenuItemType.Standard)
             : this(text, changeStateFunc, type, null)
         {
         }
 
+        /// <summary>
+        /// Creates a new <see cref="StatefulMenuItem"/>.
+        /// </summary>
+        /// <param name="text">The text to display.</param>
+        /// <param name="changeStateFunc">A function that mutates a state to another state after this <see cref="StatefulMenuItem"/> is pressed.</param>
+        /// <param name="type">The type of action which this <see cref="StatefulMenuItem"/> performs.</param>
+        /// <param name="action">A delegate to be invoked when this <see cref="StatefulMenuItem"/> is pressed.</param>
         protected StatefulMenuItem(string text, Func<T, T> changeStateFunc, MenuItemType type, Action<T> action)
             : base(text, o => changeStateFunc?.Invoke((T)o) ?? o, type, o => action?.Invoke((T)o))
         {
@@ -55,6 +95,11 @@ namespace osu.Game.Graphics.UserInterface
 
         public sealed override IconUsage? GetIconForState(object state) => GetIconForState((T)state);
 
+        /// <summary>
+        /// Retrieves the icon to be displayed for a state.
+        /// </summary>
+        /// <param name="state">The state to retrieve the relevant icon for.</param>
+        /// <returns>The icon to be displayed for <paramref name="state"/>.</returns>
         public abstract IconUsage? GetIconForState(T state);
     }
 }
diff --git a/osu.Game/Graphics/UserInterface/ThreeStateMenuItem.cs b/osu.Game/Graphics/UserInterface/ThreeStateMenuItem.cs
index d41a95daa1..e33c68bebd 100644
--- a/osu.Game/Graphics/UserInterface/ThreeStateMenuItem.cs
+++ b/osu.Game/Graphics/UserInterface/ThreeStateMenuItem.cs
@@ -6,15 +6,41 @@ using osu.Framework.Graphics.Sprites;
 
 namespace osu.Game.Graphics.UserInterface
 {
+    /// <summary>
+    /// An <see cref="OsuMenuItem"/> with three possible states.
+    /// </summary>
     public class ThreeStateMenuItem : StatefulMenuItem<ThreeStates>
     {
+        /// <summary>
+        /// Creates a new <see cref="ThreeStateMenuItem"/>.
+        /// </summary>
+        /// <param name="text">The text to display.</param>
+        /// <param name="type">The type of action which this <see cref="ThreeStateMenuItem"/> performs.</param>
         public ThreeStateMenuItem(string text, MenuItemType type = MenuItemType.Standard)
             : this(text, type, null)
         {
         }
 
+        /// <summary>
+        /// Creates a new <see cref="ThreeStateMenuItem"/>.
+        /// </summary>
+        /// <param name="text">The text to display.</param>
+        /// <param name="type">The type of action which this <see cref="ThreeStateMenuItem"/> performs.</param>
+        /// <param name="action">A delegate to be invoked when this <see cref="ThreeStateMenuItem"/> is pressed.</param>
         public ThreeStateMenuItem(string text, MenuItemType type, Action<ThreeStates> action)
-            : base(text, getNextState, type, action)
+            : this(text, getNextState, type, action)
+        {
+        }
+
+        /// <summary>
+        /// Creates a new <see cref="ThreeStateMenuItem"/>.
+        /// </summary>
+        /// <param name="text">The text to display.</param>
+        /// <param name="changeStateFunc">A function that mutates a state to another state after this <see cref="ThreeStateMenuItem"/> is pressed.</param>
+        /// <param name="type">The type of action which this <see cref="ThreeStateMenuItem"/> performs.</param>
+        /// <param name="action">A delegate to be invoked when this <see cref="ThreeStateMenuItem"/> is pressed.</param>
+        protected ThreeStateMenuItem(string text, Func<ThreeStates, ThreeStates> changeStateFunc, MenuItemType type, Action<ThreeStates> action)
+            : base(text, changeStateFunc, type, action)
         {
         }
 
@@ -44,16 +70,29 @@ namespace osu.Game.Graphics.UserInterface
 
                 case ThreeStates.Enabled:
                     return ThreeStates.Disabled;
-            }
 
-            return ThreeStates.Disabled;
+                default:
+                    throw new ArgumentOutOfRangeException(nameof(state), state, null);
+            }
         }
     }
 
     public enum ThreeStates
     {
+        /// <summary>
+        /// The current state is disabled.
+        /// </summary>
         Disabled,
+
+        /// <summary>
+        /// The current state is a combination of <see cref="Disabled"/> and <see cref="Enabled"/>.
+        /// The state becomes <see cref="Enabled"/> if the <see cref="ThreeStateMenuItem"/> is pressed.
+        /// </summary>
         Indeterminate,
+
+        /// <summary>
+        /// The current state is enabled.
+        /// </summary>
         Enabled
     }
 }
diff --git a/osu.Game/Graphics/UserInterface/ToggleMenuItem.cs b/osu.Game/Graphics/UserInterface/ToggleMenuItem.cs
index f5a442b317..f9ff9859dd 100644
--- a/osu.Game/Graphics/UserInterface/ToggleMenuItem.cs
+++ b/osu.Game/Graphics/UserInterface/ToggleMenuItem.cs
@@ -6,13 +6,27 @@ using osu.Framework.Graphics.Sprites;
 
 namespace osu.Game.Graphics.UserInterface
 {
+    /// <summary>
+    /// An <see cref="OsuMenuItem"/> which displays an enabled or disabled state.
+    /// </summary>
     public class ToggleMenuItem : StatefulMenuItem<bool>
     {
+        /// <summary>
+        /// Creates a new <see cref="ToggleMenuItem"/>.
+        /// </summary>
+        /// <param name="text">The text to display.</param>
+        /// <param name="type">The type of action which this <see cref="ToggleMenuItem"/> performs.</param>
         public ToggleMenuItem(string text, MenuItemType type = MenuItemType.Standard)
             : this(text, type, null)
         {
         }
 
+        /// <summary>
+        /// Creates a new <see cref="ToggleMenuItem"/>.
+        /// </summary>
+        /// <param name="text">The text to display.</param>
+        /// <param name="type">The type of action which this <see cref="ToggleMenuItem"/> performs.</param>
+        /// <param name="action">A delegate to be invoked when this <see cref="ToggleMenuItem"/> is pressed.</param>
         public ToggleMenuItem(string text, MenuItemType type, Action<bool> action)
             : base(text, value => !value, type, action)
         {