add param docs to event interfaces

This lets mods fully document their event handlers using the 'inheritdoc' tag.

.editorconfig

@@ -84,7 +84,7 @@ guidelines = 100
 ## Suppress warnings in rewrite facades
 ## See ReSharper docs: https://www.jetbrains.com/help/resharper/Reference__Code_Inspections_CSHARP.html.
 ##########
-[**/Rewriters/**/*Facade.cs]
+[src/SMAPI/Framework/ModLoading/Rewriters/**/*Facade.cs]
 dotnet_diagnostic.CS1591.severity = none                  # missing XML doc comment -- not meant to be used directly
 resharper_identifier_typo_highlighting = none             # identifier typo -- matches game code
 resharper_inconsistent_naming_highlighting = none         # inconsistent naming -- matches game code
@@ -92,3 +92,9 @@ resharper_local_variable_hides_member_highlighting = none # local variable hides
 resharper_parameter_hides_member_highlighting = none      # parameter hides member -- matches game code
 resharper_redundant_base_qualifier_highlighting = none    # redundant base qualifier -- deliberate for clarity, and to avoid accidentally calling a facade method
 resharper_unused_member_global_highlighting = none        # unused member -- used via rewriting
+
+##########
+## Suppress warnings in event interfaces
+##########
+[src/SMAPI/Events/I*Events.cs]
+dotnet_diagnostic.CS1572.severity = none # docblock has 'param' tag for missing parameter -- this is deliberate to let mods use <inheritdoc />

docs/release-notes.md

@@ -28,6 +28,7 @@
   * Added scroll wheel suppression via `helper.Input.SuppressScrollWheel()` (thanks to MercuriusXeno!).
   * Added `PathUtilities.AnonymizePathForDisplay` to anonymize home paths (thanks to AnotherPillow!).
   * Added asset propagation for `Data/ChairTiles`.
+  * Added parameter docs to event interfaces. This lets you fully document your event handlers like `/// <inheritdoc cref="IGameLoopEvents.SaveLoaded" />`.
   * Updated dependencies, including [FluentHttpClient](https://github.com/Pathoschild/FluentHttpClient#readme) 4.3.0 → 4.4.0 (see [changes](https://github.com/Pathoschild/FluentHttpClient/blob/develop/RELEASE-NOTES.md#440)) and [Pintail](https://github.com/Nanoray-pl/Pintail) 2.3.0 → 2.4.2 (see [changes](https://github.com/Nanoray-pl/Pintail/blob/master/docs/release-notes.md#242)).
   * The SMAPI log now includes the assembly version of each loaded mod (thanks to spacechase0!).
   * Fixed `content.Load` ignoring language override in recent versions.

src/SMAPI/Events/IContentEvents.cs

@@ -6,6 +6,8 @@ namespace StardewModdingAPI.Events
     public interface IContentEvents
     {
         /// <summary>Raised when an asset is being requested from the content pipeline.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         /// <remarks>
         /// The asset isn't necessarily being loaded yet (e.g. the game may be checking if it exists). Mods can register the changes they want to apply using methods on the event arguments. These will be applied when the asset is actually loaded.
         ///
@@ -14,13 +16,19 @@ namespace StardewModdingAPI.Events
         event EventHandler<AssetRequestedEventArgs> AssetRequested;
 
         /// <summary>Raised after one or more assets were invalidated from the content cache by a mod, so they'll be reloaded next time they're requested. If the assets will be reloaded or propagated automatically, this event is raised before that happens.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<AssetsInvalidatedEventArgs> AssetsInvalidated;
 
         /// <summary>Raised after an asset is loaded by the content pipeline, after all mod edits specified via <see cref="AssetRequested"/> have been applied.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         /// <remarks>This event is only raised if something requested the asset from the content pipeline. Invalidating an asset from the content cache won't necessarily reload it automatically.</remarks>
         event EventHandler<AssetReadyEventArgs> AssetReady;
 
         /// <summary>Raised after the game language changes.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         /// <remarks>For non-English players, this may be raised during startup when the game switches to the previously selected language.</remarks>
         event EventHandler<LocaleChangedEventArgs> LocaleChanged;
     }

src/SMAPI/Events/IDisplayEvents.cs

@@ -7,39 +7,63 @@ namespace StardewModdingAPI.Events
     public interface IDisplayEvents
     {
         /// <summary>Raised after a game menu is opened, closed, or replaced.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<MenuChangedEventArgs> MenuChanged;
 
         /// <summary>Raised before the game draws a specific step in the rendering cycle.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<RenderingStepEventArgs> RenderingStep;
 
         /// <summary>Raised after the game draws a specific step in the rendering cycle.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<RenderedStepEventArgs> RenderedStep;
 
         /// <summary>Raised before the game draws anything to the screen in a draw tick, as soon as the sprite batch is opened. The sprite batch may be closed and reopened multiple times after this event is called, but it's only raised once per draw tick. This event isn't useful for drawing to the screen, since the game will draw over it.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<RenderingEventArgs> Rendering;
 
         /// <summary>Raised after the game draws to the sprite batch in a draw tick, just before the final sprite batch is rendered to the screen. Since the game may open/close the sprite batch multiple times in a draw tick, the sprite batch may not contain everything being drawn and some things may already be rendered to the screen. Content drawn to the sprite batch at this point will be drawn over all vanilla content (including menus, HUD, and cursor).</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<RenderedEventArgs> Rendered;
 
         /// <summary>Raised before the game world is drawn to the screen. This event isn't useful for drawing to the screen, since the game will draw over it.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<RenderingWorldEventArgs> RenderingWorld;
 
         /// <summary>Raised after the game world is drawn to the sprite batch, before it's rendered to the screen. Content drawn to the sprite batch at this point will be drawn over the world, but under any active menu, HUD elements, or cursor.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<RenderedWorldEventArgs> RenderedWorld;
 
         /// <summary>When a menu is open (<see cref="Game1.activeClickableMenu"/> isn't null), raised before that menu is drawn to the screen. This includes the game's internal menus like the title screen. Content drawn to the sprite batch at this point will appear under the menu.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<RenderingActiveMenuEventArgs> RenderingActiveMenu;
 
         /// <summary>When a menu is open (<see cref="Game1.activeClickableMenu"/> isn't null), raised after that menu is drawn to the sprite batch but before it's rendered to the screen. Content drawn to the sprite batch at this point will appear over the menu and menu cursor.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<RenderedActiveMenuEventArgs> RenderedActiveMenu;
 
         /// <summary>Raised before drawing the HUD (item toolbar, clock, etc) to the screen. The vanilla HUD may be hidden at this point (e.g. because a menu is open). Content drawn to the sprite batch at this point will appear under the HUD.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<RenderingHudEventArgs> RenderingHud;
 
         /// <summary>Raised after drawing the HUD (item toolbar, clock, etc) to the sprite batch, but before it's rendered to the screen. The vanilla HUD may be hidden at this point (e.g. because a menu is open). Content drawn to the sprite batch at this point will appear over the HUD.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<RenderedHudEventArgs> RenderedHud;
 
         /// <summary>Raised after the game window is resized.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<WindowResizedEventArgs> WindowResized;
     }
 }

src/SMAPI/Events/IGameLoopEvents.cs

@@ -6,45 +6,73 @@ namespace StardewModdingAPI.Events
     public interface IGameLoopEvents
     {
         /// <summary>Raised after the game is launched, right before the first update tick. This happens once per game session (unrelated to loading saves). All mods are loaded and initialized at this point, so this is a good time to set up mod integrations.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<GameLaunchedEventArgs> GameLaunched;
 
         /// <summary>Raised before the game state is updated (≈60 times per second).</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<UpdateTickingEventArgs> UpdateTicking;
 
         /// <summary>Raised after the game state is updated (≈60 times per second).</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<UpdateTickedEventArgs> UpdateTicked;
 
         /// <summary>Raised once per second before the game state is updated.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<OneSecondUpdateTickingEventArgs> OneSecondUpdateTicking;
 
         /// <summary>Raised once per second after the game state is updated.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<OneSecondUpdateTickedEventArgs> OneSecondUpdateTicked;
 
         /// <summary>Raised before the game creates a new save file.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<SaveCreatingEventArgs> SaveCreating;
 
         /// <summary>Raised after the game finishes creating the save file.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<SaveCreatedEventArgs> SaveCreated;
 
         /// <summary>Raised before the game begins writing data to the save file (except the initial save creation).</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<SavingEventArgs> Saving;
 
         /// <summary>Raised after the game finishes writing data to the save file (except the initial save creation).</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<SavedEventArgs> Saved;
 
         /// <summary>Raised after the player loads a save slot and the world is initialized.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<SaveLoadedEventArgs> SaveLoaded;
 
         /// <summary>Raised after the game begins a new day (including when the player loads a save).</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<DayStartedEventArgs> DayStarted;
 
         /// <summary>Raised before the game ends the current day. This happens before it starts setting up the next day and before <see cref="Saving"/>.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<DayEndingEventArgs> DayEnding;
 
         /// <summary>Raised after the in-game clock time changes.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<TimeChangedEventArgs> TimeChanged;
 
         /// <summary>Raised after the game returns to the title screen.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<ReturnedToTitleEventArgs> ReturnedToTitle;
     }
 }

src/SMAPI/Events/IInputEvents.cs

@@ -6,18 +6,28 @@ namespace StardewModdingAPI.Events
     public interface IInputEvents
     {
         /// <summary>Raised after the player presses or releases any buttons on the keyboard, controller, or mouse.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<ButtonsChangedEventArgs> ButtonsChanged;
 
         /// <summary>Raised after the player presses a button on the keyboard, controller, or mouse.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<ButtonPressedEventArgs> ButtonPressed;
 
         /// <summary>Raised after the player releases a button on the keyboard, controller, or mouse.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<ButtonReleasedEventArgs> ButtonReleased;
 
         /// <summary>Raised after the player moves the in-game cursor.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<CursorMovedEventArgs> CursorMoved;
 
         /// <summary>Raised after the player scrolls the mouse wheel.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<MouseWheelScrolledEventArgs> MouseWheelScrolled;
     }
 }

src/SMAPI/Events/IMultiplayerEvents.cs

@@ -6,15 +6,23 @@ namespace StardewModdingAPI.Events
     public interface IMultiplayerEvents
     {
         /// <summary>Raised after the mod context for a peer is received. This happens before the game approves the connection (<see cref="PeerConnected"/>), so the player doesn't yet exist in the game. This is the earliest point where messages can be sent to the peer via SMAPI.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<PeerContextReceivedEventArgs> PeerContextReceived;
 
         /// <summary>Raised after a peer connection is approved by the game.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<PeerConnectedEventArgs> PeerConnected;
 
         /// <summary>Raised after a mod message is received over the network.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<ModMessageReceivedEventArgs> ModMessageReceived;
 
         /// <summary>Raised after the connection with a peer is severed.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<PeerDisconnectedEventArgs> PeerDisconnected;
     }
 }

src/SMAPI/Events/IPlayerEvents.cs

@@ -6,12 +6,18 @@ namespace StardewModdingAPI.Events
     public interface IPlayerEvents
     {
         /// <summary>Raised after items are added or removed to a player's inventory. NOTE: this event is currently only raised for the current player.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<InventoryChangedEventArgs> InventoryChanged;
 
         /// <summary>Raised after a player skill level changes. This happens as soon as they level up, not when the game notifies the player after their character goes to bed.  NOTE: this event is currently only raised for the current player.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<LevelChangedEventArgs> LevelChanged;
 
         /// <summary>Raised after a player warps to a new location. NOTE: this event is currently only raised for the current player.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<WarpedEventArgs> Warped;
     }
 }

src/SMAPI/Events/ISpecialisedEvents.cs

@@ -6,12 +6,18 @@ namespace StardewModdingAPI.Events
     public interface ISpecializedEvents
     {
         /// <summary>Raised when the low-level stage in the game's loading process has changed. This is an advanced event for mods which need to run code at specific points in the loading process. The available stages or when they happen might change without warning in future versions (e.g. due to changes in the game's load process), so mods using this event are more likely to break or have bugs. Most mods should use <see cref="IGameLoopEvents"/> instead.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<LoadStageChangedEventArgs> LoadStageChanged;
 
         /// <summary>Raised before the game state is updated (≈60 times per second), regardless of normal SMAPI validation. This event is not thread-safe and may be invoked while game logic is running asynchronously. Changes to game state in this method may crash the game or corrupt an in-progress save. Do not use this event unless you're fully aware of the context in which your code will be run. Mods using this event will trigger a stability warning in the SMAPI console.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<UnvalidatedUpdateTickingEventArgs> UnvalidatedUpdateTicking;
 
         /// <summary>Raised after the game state is updated (≈60 times per second), regardless of normal SMAPI validation. This event is not thread-safe and may be invoked while game logic is running asynchronously. Changes to game state in this method may crash the game or corrupt an in-progress save. Do not use this event unless you're fully aware of the context in which your code will be run. Mods using this event will trigger a stability warning in the SMAPI console.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<UnvalidatedUpdateTickedEventArgs> UnvalidatedUpdateTicked;
     }
 }

src/SMAPI/Events/IWorldEvents.cs

@@ -6,30 +6,48 @@ namespace StardewModdingAPI.Events
     public interface IWorldEvents
     {
         /// <summary>Raised after a game location is added or removed.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<LocationListChangedEventArgs> LocationListChanged;
 
         /// <summary>Raised after buildings are added or removed in a location.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<BuildingListChangedEventArgs> BuildingListChanged;
 
         /// <summary>Raised after debris are added or removed in a location.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<DebrisListChangedEventArgs> DebrisListChanged;
 
         /// <summary>Raised after large terrain features (like bushes) are added or removed in a location.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<LargeTerrainFeatureListChangedEventArgs> LargeTerrainFeatureListChanged;
 
         /// <summary>Raised after NPCs are added or removed in a location.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<NpcListChangedEventArgs> NpcListChanged;
 
         /// <summary>Raised after objects are added or removed in a location.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<ObjectListChangedEventArgs> ObjectListChanged;
 
         /// <summary>Raised after items are added or removed from a chest.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<ChestInventoryChangedEventArgs> ChestInventoryChanged;
 
         /// <summary>Raised after terrain features (like floors and trees) are added or removed in a location.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<TerrainFeatureListChangedEventArgs> TerrainFeatureListChanged;
 
         /// <summary>Raised after furniture are added or removed in a location.</summary>
+        /// <param name="sender">The event sender. This isn't applicable to SMAPI events, and is always null.</param>
+        /// <param name="e">The event data.</param>
         event EventHandler<FurnitureListChangedEventArgs> FurnitureListChanged;
     }
 }