document & format event code

1 files changed, 136 insertions, 98 deletions

diff --git a/src/StardewModdingAPI/Events/GraphicsEvents.cs b/src/StardewModdingAPI/Events/GraphicsEvents.cs
index 1435bc37..fe38c1bb 100644
--- a/src/StardewModdingAPI/Events/GraphicsEvents.cs
+++ b/src/StardewModdingAPI/Events/GraphicsEvents.cs
@@ -2,161 +2,199 @@
 
 namespace StardewModdingAPI.Events
 {
-    /// <summary>
-    /// 
-    /// </summary>
+    /// <summary>Events raised during the game's draw loop, when the game is rendering content to the window.</summary>
     public static class GraphicsEvents
     {
-        /// <summary>
-        /// Occurs when the form (game) is resized.
-        /// </summary>
+        /*********
+        ** Events
+        *********/
+        /****
+        ** Generic events
+        ****/
+        /// <summary>Raised after the game window is resized.</summary>
         public static event EventHandler Resize = delegate { };
 
-        /// <summary>
-        /// Occurs before anything is drawn.
-        /// </summary>
-        public static event EventHandler OnPreRenderEvent = delegate { };
+        /// <summary>Raised when drawing debug information to the screen (when <see cref="StardewModdingAPI.Inheritance.SGame.Debug"/> is true). This is called after the sprite batch is begun. If you just want to add debug info, use <see cref="StardewModdingAPI.Inheritance.SGame.DebugMessageQueue" /> in your update loop.</summary>
+        public static event EventHandler DrawDebug = delegate { };
 
-        /// <summary>
-        /// Occurs before the GUI is drawn.
-        /// </summary>
-        public static event EventHandler OnPreRenderGuiEvent = delegate { };
+        /// <summary>Obsolete.</summary>
+        [Obsolete("Use the other Pre/Post render events instead.")]
+        public static event EventHandler DrawTick = delegate { };
 
-        /// <summary>
-        /// Occurs after the GUI is drawn.
-        /// </summary>
-        public static event EventHandler OnPostRenderGuiEvent = delegate { };
+        /// <summary>Obsolete.</summary>
+        [Obsolete("Use the other Pre/Post render events instead. All of them will automatically be drawn into the render target if needed.")]
+        public static event EventHandler DrawInRenderTargetTick = delegate { };
+
+        /****
+        ** Main render events
+        ****/
+        /// <summary>Raised before drawing everything to the screen during a draw loop.</summary>
+        public static event EventHandler OnPreRenderEvent = delegate { };
 
-        /// <summary>
-        /// Occurs before the HUD is drawn.
-        /// </summary>
+        /// <summary>Raised after drawing everything to the screen during a draw loop.</summary>
+        public static event EventHandler OnPostRenderEvent = delegate { };
+
+        /****
+        ** HUD events
+        ****/
+        /// <summary>Raised before drawing the HUD (item toolbar, clock, etc) to the screen. The HUD is available at this point, but not necessarily visible. (For example, the event is raised even if a menu is open.)</summary>
         public static event EventHandler OnPreRenderHudEvent = delegate { };
 
-        /// <summary>
-        /// Occurs after the HUD is drawn.
-        /// </summary>
+        /// <summary>Equivalent to <see cref="OnPreRenderHudEvent"/>, but invoked even if the HUD isn't available.</summary>
+        public static event EventHandler OnPreRenderHudEventNoCheck = delegate { };
+
+        /// <summary>Raised after drawing the HUD (item toolbar, clock, etc) to the screen. The HUD is available at this point, but not necessarily visible. (For example, the event is raised even if a menu is open.)</summary>
         public static event EventHandler OnPostRenderHudEvent = delegate { };
 
-        /// <summary>
-        /// Occurs after everything is drawn.
-        /// </summary>
-        public static event EventHandler OnPostRenderEvent = delegate { };
+        /// <summary>Equivalent to <see cref="OnPostRenderHudEvent"/>, but invoked even if the HUD isn't available.</summary>
+        public static event EventHandler OnPostRenderHudEventNoCheck = delegate { };
 
-        /// <summary>
-        /// Occurs before the GUI is drawn. Does not check for conditional statements.
-        /// </summary>
-        public static event EventHandler OnPreRenderGuiEventNoCheck = delegate { };
+        /****
+        ** GUI events
+        ****/
+        /// <summary>Raised before drawing a menu to the screen during a draw loop. This includes the game's internal menus like the title screen.</summary>
+        public static event EventHandler OnPreRenderGuiEvent = delegate { };
 
-        /// <summary>
-        /// Occurs after the GUI is drawn. Does not check for conditional statements.
-        /// </summary>
-        public static event EventHandler OnPostRenderGuiEventNoCheck = delegate { };
+        /// <summary>Equivalent to <see cref="OnPreRenderGuiEvent"/>, but invoked even if there's no menu being drawn.</summary>
+        public static event EventHandler OnPreRenderGuiEventNoCheck = delegate { };
 
-        /// <summary>
-        /// Occurs before the HUD is drawn. Does not check for conditional statements.
-        /// </summary>
-        public static event EventHandler OnPreRenderHudEventNoCheck = delegate { };
+        /// <summary>Raised after drawing a menu to the screen during a draw loop. This includes the game's internal menus like the title screen.</summary>
+        public static event EventHandler OnPostRenderGuiEvent = delegate { };
 
-        /// <summary>
-        /// Occurs after the HUD is drawn. Does not check for conditional statements.
-        /// </summary>
-        public static event EventHandler OnPostRenderHudEventNoCheck = delegate { };
+        /// <summary>Equivalent to <see cref="OnPreRenderGuiEvent"/>, but invoked even if there's no menu being drawn.</summary>
+        public static event EventHandler OnPostRenderGuiEventNoCheck = delegate { };
 
-        /// <summary>
-        /// Draws when SGame.Debug is true. F3 toggles this.
-        /// Game1.spriteBatch.Begin() is pre-called.
-        /// Do not make end or begin calls to the spritebatch.
-        /// If you are only trying to add debug information, use SGame.DebugMessageQueue in your Update loop.
-        /// </summary>
-        public static event EventHandler DrawDebug = delegate { };
 
-        internal static void InvokeDrawDebug(object sender, EventArgs e)
+        /*********
+        ** Internal methods
+        *********/
+        /****
+        ** Generic events
+        ****/
+        /// <summary>Raise a <see cref="Resize"/> event.</summary>
+        /// <param name="sender">The object which raised the event.</param>
+        /// <param name="e">The event arguments.</param>
+        internal static void InvokeResize(object sender, EventArgs e)
         {
-            DrawDebug.Invoke(sender, e);
+            GraphicsEvents.Resize.Invoke(sender, e);
         }
 
-        internal static void InvokeOnPreRenderEvent(object sender, EventArgs e)
+        /// <summary>Raise a <see cref="DrawDebug"/> event.</summary>
+        /// <param name="sender">The object which raised the event.</param>
+        /// <param name="e">The event arguments.</param>
+        internal static void InvokeDrawDebug(object sender, EventArgs e)
         {
-            OnPreRenderEvent.Invoke(sender, e);
+            GraphicsEvents.DrawDebug.Invoke(sender, e);
         }
 
-        internal static void InvokeOnPreRenderGuiEvent(object sender, EventArgs e)
+        /// <summary>Raise a <see cref="DrawTick"/> event.</summary>
+        [Obsolete("Should not be used.")]
+        public static void InvokeDrawTick()
         {
-            OnPreRenderGuiEvent.Invoke(sender, e);
+            try
+            {
+                GraphicsEvents.DrawTick.Invoke(null, EventArgs.Empty);
+            }
+            catch (Exception ex)
+            {
+                Log.AsyncR("An exception occured in a Mod's DrawTick: " + ex);
+            }
         }
 
-        internal static void InvokeOnPostRenderGuiEvent(object sender, EventArgs e)
+        /// <summary>Raise a <see cref="DrawInRenderTargetTick"/> event.</summary>
+        [Obsolete("Should not be used.")]
+        public static void InvokeDrawInRenderTargetTick()
         {
-            OnPostRenderGuiEvent.Invoke(sender, e);
+            GraphicsEvents.DrawInRenderTargetTick.Invoke(null, EventArgs.Empty);
         }
 
-        internal static void InvokeOnPreRenderHudEvent(object sender, EventArgs e)
+        /****
+        ** Main render events
+        ****/
+        /// <summary>Raise an <see cref="OnPreRenderEvent"/> event.</summary>
+        /// <param name="sender">The object which raised the event.</param>
+        /// <param name="e">The event arguments.</param>
+        internal static void InvokeOnPreRenderEvent(object sender, EventArgs e)
         {
-            OnPreRenderHudEvent.Invoke(sender, e);
+            GraphicsEvents.OnPreRenderEvent.Invoke(sender, e);
         }
 
-        internal static void InvokeOnPostRenderHudEvent(object sender, EventArgs e)
+        /// <summary>Raise an <see cref="OnPostRenderEvent"/> event.</summary>
+        /// <param name="sender">The object which raised the event.</param>
+        /// <param name="e">The event arguments.</param>
+        internal static void InvokeOnPostRenderEvent(object sender, EventArgs e)
         {
-            OnPostRenderHudEvent.Invoke(sender, e);
+            GraphicsEvents.OnPostRenderEvent.Invoke(sender, e);
         }
 
-        internal static void InvokeOnPostRenderEvent(object sender, EventArgs e)
+        /****
+        ** HUD events
+        ****/
+        /// <summary>Raise an <see cref="OnPreRenderGuiEvent"/> event.</summary>
+        /// <param name="sender">The object which raised the event.</param>
+        /// <param name="e">The event arguments.</param>
+        internal static void InvokeOnPreRenderGuiEvent(object sender, EventArgs e)
         {
-            OnPostRenderEvent.Invoke(sender, e);
+            GraphicsEvents.OnPreRenderGuiEvent.Invoke(sender, e);
         }
 
+        /// <summary>Raise an <see cref="OnPreRenderGuiEventNoCheck"/> event.</summary>
+        /// <param name="sender">The object which raised the event.</param>
+        /// <param name="e">The event arguments.</param>
         internal static void InvokeOnPreRenderGuiEventNoCheck(object sender, EventArgs e)
         {
-            OnPreRenderGuiEventNoCheck.Invoke(sender, e);
+            GraphicsEvents.OnPreRenderGuiEventNoCheck.Invoke(sender, e);
         }
 
-        internal static void InvokeOnPostRenderGuiEventNoCheck(object sender, EventArgs e)
+        /// <summary>Raise an <see cref="OnPostRenderGuiEvent"/> event.</summary>
+        /// <param name="sender">The object which raised the event.</param>
+        /// <param name="e">The event arguments.</param>
+        internal static void InvokeOnPostRenderGuiEvent(object sender, EventArgs e)
         {
-            OnPostRenderGuiEventNoCheck.Invoke(sender, e);
+            GraphicsEvents.OnPostRenderGuiEvent.Invoke(sender, e);
         }
 
-        internal static void InvokeOnPreRenderHudEventNoCheck(object sender, EventArgs e)
+        /// <summary>Raise an <see cref="OnPostRenderGuiEventNoCheck"/> event.</summary>
+        /// <param name="sender">The object which raised the event.</param>
+        /// <param name="e">The event arguments.</param>
+        internal static void InvokeOnPostRenderGuiEventNoCheck(object sender, EventArgs e)
         {
-            OnPreRenderHudEventNoCheck.Invoke(sender, e);
+            GraphicsEvents.OnPostRenderGuiEventNoCheck.Invoke(sender, e);
         }
 
-        internal static void InvokeOnPostRenderHudEventNoCheck(object sender, EventArgs e)
+        /****
+        ** GUI events
+        ****/
+        /// <summary>Raise an <see cref="OnPreRenderHudEvent"/> event.</summary>
+        /// <param name="sender">The object which raised the event.</param>
+        /// <param name="e">The event arguments.</param>
+        internal static void InvokeOnPreRenderHudEvent(object sender, EventArgs e)
         {
-            OnPostRenderHudEventNoCheck.Invoke(sender, e);
+            GraphicsEvents.OnPreRenderHudEvent.Invoke(sender, e);
         }
 
-        internal static void InvokeResize(object sender, EventArgs e)
+        /// <summary>Raise an <see cref="OnPreRenderHudEventNoCheck"/> event.</summary>
+        /// <param name="sender">The object which raised the event.</param>
+        /// <param name="e">The event arguments.</param>
+        internal static void InvokeOnPreRenderHudEventNoCheck(object sender, EventArgs e)
         {
-            Resize.Invoke(sender, e);
+            GraphicsEvents.OnPreRenderHudEventNoCheck.Invoke(sender, e);
         }
 
-        #region To Remove
-
-        [Obsolete("Use the other Pre/Post render events instead.")]
-        public static event EventHandler DrawTick = delegate { };
-
-        [Obsolete("Use the other Pre/Post render events instead. All of them will automatically be drawn into the render target if needed.")]
-        public static event EventHandler DrawInRenderTargetTick = delegate { };
-
-        [Obsolete("Should not be used.")]
-        public static void InvokeDrawTick()
+        /// <summary>Raise an <see cref="OnPostRenderHudEvent"/> event.</summary>
+        /// <param name="sender">The object which raised the event.</param>
+        /// <param name="e">The event arguments.</param>
+        internal static void InvokeOnPostRenderHudEvent(object sender, EventArgs e)
         {
-            try
-            {
-                DrawTick.Invoke(null, EventArgs.Empty);
-            }
-            catch (Exception ex)
-            {
-                Log.AsyncR("An exception occured in a Mod's DrawTick: " + ex);
-            }
+            GraphicsEvents.OnPostRenderHudEvent.Invoke(sender, e);
         }
 
-        [Obsolete("Should not be used.")]
-        public static void InvokeDrawInRenderTargetTick()
+        /// <summary>Raise an <see cref="OnPostRenderHudEventNoCheck"/> event.</summary>
+        /// <param name="sender">The object which raised the event.</param>
+        /// <param name="e">The event arguments.</param>
+        internal static void InvokeOnPostRenderHudEventNoCheck(object sender, EventArgs e)
         {
-            DrawInRenderTargetTick.Invoke(null, EventArgs.Empty);
+            GraphicsEvents.OnPostRenderHudEventNoCheck.Invoke(sender, e);
         }
-
-        #endregion
     }
-}
\ No newline at end of file
+}