From 828be405e11dd8bc7f8a3692d2c74517734f67a5 Mon Sep 17 00:00:00 2001 From: Jesse Plamondon-Willard Date: Sun, 30 Aug 2020 22:53:19 -0400 Subject: use inheritdoc --- src/SMAPI/Framework/ModHelpers/BaseHelper.cs | 4 +-- src/SMAPI/Framework/ModHelpers/CommandHelper.cs | 13 ++----- src/SMAPI/Framework/ModHelpers/ContentHelper.cs | 41 ++++++---------------- .../Framework/ModHelpers/ContentPackHelper.cs | 13 ++----- src/SMAPI/Framework/ModHelpers/DataHelper.cs | 34 ++++-------------- src/SMAPI/Framework/ModHelpers/InputHelper.cs | 14 +++----- src/SMAPI/Framework/ModHelpers/ModHelper.cs | 31 ++++++++-------- .../Framework/ModHelpers/ModRegistryHelper.cs | 15 +++----- .../Framework/ModHelpers/MultiplayerHelper.cs | 19 +++------- src/SMAPI/Framework/ModHelpers/ReflectionHelper.cs | 34 ++++-------------- .../Framework/ModHelpers/TranslationHelper.cs | 13 +++---- 11 files changed, 64 insertions(+), 167 deletions(-) (limited to 'src/SMAPI/Framework/ModHelpers') diff --git a/src/SMAPI/Framework/ModHelpers/BaseHelper.cs b/src/SMAPI/Framework/ModHelpers/BaseHelper.cs index 16032da1..5a3d4bed 100644 --- a/src/SMAPI/Framework/ModHelpers/BaseHelper.cs +++ b/src/SMAPI/Framework/ModHelpers/BaseHelper.cs @@ -1,4 +1,4 @@ -namespace StardewModdingAPI.Framework.ModHelpers +namespace StardewModdingAPI.Framework.ModHelpers { /// The common base class for mod helpers. internal abstract class BaseHelper : IModLinked @@ -6,7 +6,7 @@ /********* ** Accessors *********/ - /// The unique ID of the mod for which the helper was created. + /// public string ModID { get; } diff --git a/src/SMAPI/Framework/ModHelpers/CommandHelper.cs b/src/SMAPI/Framework/ModHelpers/CommandHelper.cs index e9d53d84..600f867f 100644 --- a/src/SMAPI/Framework/ModHelpers/CommandHelper.cs +++ b/src/SMAPI/Framework/ModHelpers/CommandHelper.cs @@ -28,23 +28,14 @@ namespace StardewModdingAPI.Framework.ModHelpers this.CommandManager = commandManager; } - /// Add a console command. - /// The command name, which the user must type to trigger it. - /// The human-readable documentation shown when the player runs the built-in 'help' command. - /// The method to invoke when the command is triggered. This method is passed the command name and arguments submitted by the user. - /// The or is null or empty. - /// The is not a valid format. - /// There's already a command with that name. + /// public ICommandHelper Add(string name, string documentation, Action callback) { this.CommandManager.Add(this.Mod, name, documentation, callback); return this; } - /// Trigger a command. - /// The command name. - /// The command arguments. - /// Returns whether a matching command was triggered. + /// public bool Trigger(string name, string[] arguments) { return this.CommandManager.Trigger(name, arguments); diff --git a/src/SMAPI/Framework/ModHelpers/ContentHelper.cs b/src/SMAPI/Framework/ModHelpers/ContentHelper.cs index 23e45fd1..80f61c13 100644 --- a/src/SMAPI/Framework/ModHelpers/ContentHelper.cs +++ b/src/SMAPI/Framework/ModHelpers/ContentHelper.cs @@ -40,10 +40,10 @@ namespace StardewModdingAPI.Framework.ModHelpers /********* ** Accessors *********/ - /// The game's current locale code (like pt-BR). + /// public string CurrentLocale => this.GameContentManager.GetLocale(); - /// The game's current locale as an enum value. + /// public LocalizedContentManager.LanguageCode CurrentLocaleConstant => this.GameContentManager.Language; /// The observable implementation of . @@ -52,10 +52,10 @@ namespace StardewModdingAPI.Framework.ModHelpers /// The observable implementation of . internal ObservableCollection ObservableAssetLoaders { get; } = new ObservableCollection(); - /// Interceptors which provide the initial versions of matching content assets. + /// public IList AssetLoaders => this.ObservableAssetLoaders; - /// Interceptors which edit matching content assets after they're loaded. + /// public IList AssetEditors => this.ObservableAssetEditors; @@ -80,12 +80,7 @@ namespace StardewModdingAPI.Framework.ModHelpers this.Monitor = monitor; } - /// Load content from the game folder or mod folder (if not already cached), and return it. When loading a .png file, this must be called outside the game's draw loop. - /// The expected data type. The main supported types are , , and dictionaries; other types may be supported by the game's content pipeline. - /// The asset key to fetch (if the is ), or the local path to a content file relative to the mod folder. - /// Where to search for a matching content asset. - /// The is empty or contains invalid characters. - /// The content asset couldn't be loaded (e.g. because it doesn't exist). + /// public T Load(string key, ContentSource source = ContentSource.ModFolder) { try @@ -109,18 +104,14 @@ namespace StardewModdingAPI.Framework.ModHelpers } } - /// Normalize an asset name so it's consistent with those generated by the game. This is mainly useful for string comparisons like on generated asset names, and isn't necessary when passing asset names into other content helper methods. - /// The asset key. + /// [Pure] public string NormalizeAssetName(string assetName) { return this.ModContentManager.AssertAndNormalizeAssetName(assetName); } - /// Get the underlying key in the game's content cache for an asset. This can be used to load custom map tilesheets, but should be avoided when you can use the content API instead. This does not validate whether the asset exists. - /// The asset key to fetch (if the is ), or the local path to a content file relative to the mod folder. - /// Where to search for a matching content asset. - /// The is empty or contains invalid characters. + /// public string GetActualAssetKey(string key, ContentSource source = ContentSource.ModFolder) { switch (source) @@ -136,10 +127,7 @@ namespace StardewModdingAPI.Framework.ModHelpers } } - /// Remove an asset from the content cache so it's reloaded on the next request. This will reload core game assets if needed, but references to the former asset will still show the previous content. - /// The asset key to invalidate in the content folder. - /// The is empty or contains invalid characters. - /// Returns whether the given asset key was cached. + /// public bool InvalidateCache(string key) { string actualKey = this.GetActualAssetKey(key, ContentSource.GameContent); @@ -147,28 +135,21 @@ namespace StardewModdingAPI.Framework.ModHelpers return this.ContentCore.InvalidateCache(asset => asset.AssetNameEquals(actualKey)).Any(); } - /// Remove all assets of the given type from the cache so they're reloaded on the next request. This can be a very expensive operation and should only be used in very specific cases. This will reload core game assets if needed, but references to the former assets will still show the previous content. - /// The asset type to remove from the cache. - /// Returns whether any assets were invalidated. + /// public bool InvalidateCache() { this.Monitor.Log($"Requested cache invalidation for all assets of type {typeof(T)}. This is an expensive operation and should be avoided if possible.", LogLevel.Trace); return this.ContentCore.InvalidateCache((key, type) => typeof(T).IsAssignableFrom(type)).Any(); } - /// Remove matching assets from the content cache so they're reloaded on the next request. This will reload core game assets if needed, but references to the former asset will still show the previous content. - /// A predicate matching the assets to invalidate. - /// Returns whether any cache entries were invalidated. + /// public bool InvalidateCache(Func predicate) { this.Monitor.Log("Requested cache invalidation for all assets matching a predicate.", LogLevel.Trace); return this.ContentCore.InvalidateCache(predicate).Any(); } - /// Get a patch helper for arbitrary data. - /// The data type. - /// The asset data. - /// The asset name. This is only used for tracking purposes and has no effect on the patch helper. + /// public IAssetData GetPatchHelper(T data, string assetName = null) { if (data == null) diff --git a/src/SMAPI/Framework/ModHelpers/ContentPackHelper.cs b/src/SMAPI/Framework/ModHelpers/ContentPackHelper.cs index acdd82a0..d39abc7d 100644 --- a/src/SMAPI/Framework/ModHelpers/ContentPackHelper.cs +++ b/src/SMAPI/Framework/ModHelpers/ContentPackHelper.cs @@ -32,27 +32,20 @@ namespace StardewModdingAPI.Framework.ModHelpers this.CreateContentPack = createContentPack; } - /// Get all content packs loaded for this mod. + /// public IEnumerable GetOwned() { return this.ContentPacks.Value; } - /// Create a temporary content pack to read files from a directory, using randomized manifest fields. This will generate fake manifest data; any manifest.json in the directory will be ignored. Temporary content packs will not appear in the SMAPI log and update checks will not be performed. - /// The absolute directory path containing the content pack files. + /// public IContentPack CreateFake(string directoryPath) { string id = Guid.NewGuid().ToString("N"); return this.CreateTemporary(directoryPath, id, id, id, id, new SemanticVersion(1, 0, 0)); } - /// Create a temporary content pack to read files from a directory. Temporary content packs will not appear in the SMAPI log and update checks will not be performed. - /// The absolute directory path containing the content pack files. - /// The content pack's unique ID. - /// The content pack name. - /// The content pack description. - /// The content pack author's name. - /// The content pack version. + /// public IContentPack CreateTemporary(string directoryPath, string id, string name, string description, string author, ISemanticVersion version) { // validate diff --git a/src/SMAPI/Framework/ModHelpers/DataHelper.cs b/src/SMAPI/Framework/ModHelpers/DataHelper.cs index 6cde849c..c232a6dd 100644 --- a/src/SMAPI/Framework/ModHelpers/DataHelper.cs +++ b/src/SMAPI/Framework/ModHelpers/DataHelper.cs @@ -39,11 +39,7 @@ namespace StardewModdingAPI.Framework.ModHelpers /**** ** JSON file ****/ - /// Read data from a JSON file in the mod's folder. - /// The model type. This should be a plain class that has public properties for the data you want. The properties can be complex types. - /// The file path relative to the mod folder. - /// Returns the deserialized model, or null if the file doesn't exist or is empty. - /// The is not relative or contains directory climbing (../). + /// public TModel ReadJsonFile(string path) where TModel : class { if (!PathUtilities.IsSafeRelativePath(path)) @@ -55,11 +51,7 @@ namespace StardewModdingAPI.Framework.ModHelpers : null; } - /// Save data to a JSON file in the mod's folder. - /// The model type. This should be a plain class that has public properties for the data you want. The properties can be complex types. - /// The file path relative to the mod folder. - /// The arbitrary data to save. - /// The is not relative or contains directory climbing (../). + /// public void WriteJsonFile(string path, TModel data) where TModel : class { if (!PathUtilities.IsSafeRelativePath(path)) @@ -72,11 +64,7 @@ namespace StardewModdingAPI.Framework.ModHelpers /**** ** Save file ****/ - /// Read arbitrary data stored in the current save slot. This is only possible if a save has been loaded. - /// The model type. This should be a plain class that has public properties for the data you want. The properties can be complex types. - /// The unique key identifying the data. - /// Returns the parsed data, or null if the entry doesn't exist or is empty. - /// The player hasn't loaded a save file yet or isn't the main player. + /// public TModel ReadSaveData(string key) where TModel : class { if (Context.LoadStage == LoadStage.None) @@ -94,11 +82,7 @@ namespace StardewModdingAPI.Framework.ModHelpers return null; } - /// Save arbitrary data to the current save slot. This is only possible if a save has been loaded, and the data will be lost if the player exits without saving the current day. - /// The model type. This should be a plain class that has public properties for the data you want. The properties can be complex types. - /// The unique key identifying the data. - /// The arbitrary data to save. - /// The player hasn't loaded a save file yet or isn't the main player. + /// public void WriteSaveData(string key, TModel model) where TModel : class { if (Context.LoadStage == LoadStage.None) @@ -123,10 +107,7 @@ namespace StardewModdingAPI.Framework.ModHelpers /**** ** Global app data ****/ - /// Read arbitrary data stored on the local computer, synchronised by GOG/Steam if applicable. - /// The model type. This should be a plain class that has public properties for the data you want. The properties can be complex types. - /// The unique key identifying the data. - /// Returns the parsed data, or null if the entry doesn't exist or is empty. + /// public TModel ReadGlobalData(string key) where TModel : class { string path = this.GetGlobalDataPath(key); @@ -135,10 +116,7 @@ namespace StardewModdingAPI.Framework.ModHelpers : null; } - /// Save arbitrary data to the local computer, synchronised by GOG/Steam if applicable. - /// The model type. This should be a plain class that has public properties for the data you want. The properties can be complex types. - /// The unique key identifying the data. - /// The arbitrary data to save. + /// public void WriteGlobalData(string key, TModel data) where TModel : class { string path = this.GetGlobalDataPath(key); diff --git a/src/SMAPI/Framework/ModHelpers/InputHelper.cs b/src/SMAPI/Framework/ModHelpers/InputHelper.cs index 134ba8d1..09ce3c65 100644 --- a/src/SMAPI/Framework/ModHelpers/InputHelper.cs +++ b/src/SMAPI/Framework/ModHelpers/InputHelper.cs @@ -24,35 +24,31 @@ namespace StardewModdingAPI.Framework.ModHelpers this.InputState = inputState; } - /// Get the current cursor position. + /// public ICursorPosition GetCursorPosition() { return this.InputState.CursorPosition; } - /// Get whether a button is currently pressed. - /// The button. + /// public bool IsDown(SButton button) { return this.InputState.IsDown(button); } - /// Get whether a button is currently suppressed, so the game won't see it. - /// The button. + /// public bool IsSuppressed(SButton button) { return this.InputState.IsSuppressed(button); } - /// Prevent the game from handling a button press. This doesn't prevent other mods from receiving the event. - /// The button to suppress. + /// public void Suppress(SButton button) { this.InputState.OverrideButton(button, setDown: false); } - /// Get the state of a button. - /// The button to check. + /// public SButtonState GetState(SButton button) { return this.InputState.GetState(button); diff --git a/src/SMAPI/Framework/ModHelpers/ModHelper.cs b/src/SMAPI/Framework/ModHelpers/ModHelper.cs index 9fbb6072..d9fc8621 100644 --- a/src/SMAPI/Framework/ModHelpers/ModHelper.cs +++ b/src/SMAPI/Framework/ModHelpers/ModHelper.cs @@ -11,37 +11,37 @@ namespace StardewModdingAPI.Framework.ModHelpers /********* ** Accessors *********/ - /// The full path to the mod's folder. + /// public string DirectoryPath { get; } - /// Manages access to events raised by SMAPI, which let your mod react when something happens in the game. + /// public IModEvents Events { get; } - /// An API for loading content assets. + /// public IContentHelper Content { get; } - /// An API for managing content packs. + /// public IContentPackHelper ContentPacks { get; } - /// An API for reading and writing persistent mod data. + /// public IDataHelper Data { get; } - /// An API for checking and changing input state. + /// public IInputHelper Input { get; } - /// An API for accessing private game code. + /// public IReflectionHelper Reflection { get; } - /// an API for fetching metadata about loaded mods. + /// public IModRegistry ModRegistry { get; } - /// An API for managing console commands. + /// public ICommandHelper ConsoleCommands { get; } - /// Provides multiplayer utilities. + /// public IMultiplayerHelper Multiplayer { get; } - /// An API for reading translations stored in the mod's i18n folder, with one file per locale (like en.json) containing a flat key => value structure. Translations are fetched with locale fallback, so missing translations are filled in from broader locales (like pt-BR.json < pt.json < default.json). + /// public ITranslationHelper Translation { get; } @@ -89,8 +89,7 @@ namespace StardewModdingAPI.Framework.ModHelpers /**** ** Mod config file ****/ - /// Read the mod's configuration file (and create it if needed). - /// The config class type. This should be a plain class that has public properties for the settings you want. These can be complex types. + /// public TConfig ReadConfig() where TConfig : class, new() { @@ -99,9 +98,7 @@ namespace StardewModdingAPI.Framework.ModHelpers return config; } - /// Save to the mod's configuration file. - /// The config class type. - /// The config settings to save. + /// public void WriteConfig(TConfig config) where TConfig : class, new() { @@ -111,7 +108,7 @@ namespace StardewModdingAPI.Framework.ModHelpers /**** ** Disposal ****/ - /// Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources. + /// public void Dispose() { // nothing to dispose yet diff --git a/src/SMAPI/Framework/ModHelpers/ModRegistryHelper.cs b/src/SMAPI/Framework/ModHelpers/ModRegistryHelper.cs index f42cb085..ef1ad30c 100644 --- a/src/SMAPI/Framework/ModHelpers/ModRegistryHelper.cs +++ b/src/SMAPI/Framework/ModHelpers/ModRegistryHelper.cs @@ -38,28 +38,25 @@ namespace StardewModdingAPI.Framework.ModHelpers this.Monitor = monitor; } - /// Get metadata for all loaded mods. + /// public IEnumerable GetAll() { return this.Registry.GetAll(); } - /// Get metadata for a loaded mod. - /// The mod's unique ID. - /// Returns the matching mod's metadata, or null if not found. + /// public IModInfo Get(string uniqueID) { return this.Registry.Get(uniqueID); } - /// Get whether a mod has been loaded. - /// The mod's unique ID. + /// public bool IsLoaded(string uniqueID) { return this.Registry.Get(uniqueID) != null; } - /// Get the API provided by a mod, or null if it has none. This signature requires using the API to access the API's properties and methods. + /// public object GetApi(string uniqueID) { // validate ready @@ -76,9 +73,7 @@ namespace StardewModdingAPI.Framework.ModHelpers return mod?.Api; } - /// Get the API provided by a mod, mapped to a given interface which specifies the expected properties and methods. If the mod has no API or it's not compatible with the given interface, get null. - /// The interface which matches the properties and methods you intend to access. - /// The mod's unique ID. + /// public TInterface GetApi(string uniqueID) where TInterface : class { // get raw API diff --git a/src/SMAPI/Framework/ModHelpers/MultiplayerHelper.cs b/src/SMAPI/Framework/ModHelpers/MultiplayerHelper.cs index c62dd121..a7ce8692 100644 --- a/src/SMAPI/Framework/ModHelpers/MultiplayerHelper.cs +++ b/src/SMAPI/Framework/ModHelpers/MultiplayerHelper.cs @@ -1,4 +1,3 @@ -using System; using System.Collections.Generic; using StardewModdingAPI.Framework.Networking; using StardewValley; @@ -27,21 +26,19 @@ namespace StardewModdingAPI.Framework.ModHelpers this.Multiplayer = multiplayer; } - /// Get a new multiplayer ID. + /// public long GetNewID() { return this.Multiplayer.getNewID(); } - /// Get the locations which are being actively synced from the host. + /// public IEnumerable GetActiveLocations() { return this.Multiplayer.activeLocations(); } - /// Get a connected player. - /// The player's unique ID. - /// Returns the connected player, or null if no such player is connected. + /// public IMultiplayerPeer GetConnectedPlayer(long id) { return this.Multiplayer.Peers.TryGetValue(id, out MultiplayerPeer peer) @@ -49,19 +46,13 @@ namespace StardewModdingAPI.Framework.ModHelpers : null; } - /// Get all connected players. + /// public IEnumerable GetConnectedPlayers() { return this.Multiplayer.Peers.Values; } - /// Send a message to mods installed by connected players. - /// The data type. This can be a class with a default constructor, or a value type. - /// The data to send over the network. - /// A message type which receiving mods can use to decide whether it's the one they want to handle, like SetPlayerLocation. This doesn't need to be globally unique, since mods should check the originating mod ID. - /// The mod IDs which should receive the message on the destination computers, or null for all mods. Specifying mod IDs is recommended to improve performance, unless it's a general-purpose broadcast. - /// The values for the players who should receive the message, or null for all players. If you don't need to broadcast to all players, specifying player IDs is recommended to reduce latency. - /// The or is null. + /// public void SendMessage(TMessage message, string messageType, string[] modIDs = null, long[] playerIDs = null) { this.Multiplayer.BroadcastModMessage( diff --git a/src/SMAPI/Framework/ModHelpers/ReflectionHelper.cs b/src/SMAPI/Framework/ModHelpers/ReflectionHelper.cs index 916c215d..5a4ea742 100644 --- a/src/SMAPI/Framework/ModHelpers/ReflectionHelper.cs +++ b/src/SMAPI/Framework/ModHelpers/ReflectionHelper.cs @@ -32,11 +32,7 @@ namespace StardewModdingAPI.Framework.ModHelpers this.Reflector = reflector; } - /// Get an instance field. - /// The field type. - /// The object which has the field. - /// The field name. - /// Whether to throw an exception if the field is not found. + /// public IReflectedField GetField(object obj, string name, bool required = true) { return this.AssertAccessAllowed( @@ -44,11 +40,7 @@ namespace StardewModdingAPI.Framework.ModHelpers ); } - /// Get a static field. - /// The field type. - /// The type which has the field. - /// The field name. - /// Whether to throw an exception if the field is not found. + /// public IReflectedField GetField(Type type, string name, bool required = true) { return this.AssertAccessAllowed( @@ -56,11 +48,7 @@ namespace StardewModdingAPI.Framework.ModHelpers ); } - /// Get an instance property. - /// The property type. - /// The object which has the property. - /// The property name. - /// Whether to throw an exception if the property is not found. + /// public IReflectedProperty GetProperty(object obj, string name, bool required = true) { return this.AssertAccessAllowed( @@ -68,11 +56,7 @@ namespace StardewModdingAPI.Framework.ModHelpers ); } - /// Get a static property. - /// The property type. - /// The type which has the property. - /// The property name. - /// Whether to throw an exception if the property is not found. + /// public IReflectedProperty GetProperty(Type type, string name, bool required = true) { return this.AssertAccessAllowed( @@ -80,10 +64,7 @@ namespace StardewModdingAPI.Framework.ModHelpers ); } - /// Get an instance method. - /// The object which has the method. - /// The field name. - /// Whether to throw an exception if the field is not found. + /// public IReflectedMethod GetMethod(object obj, string name, bool required = true) { return this.AssertAccessAllowed( @@ -91,10 +72,7 @@ namespace StardewModdingAPI.Framework.ModHelpers ); } - /// Get a static method. - /// The type which has the method. - /// The field name. - /// Whether to throw an exception if the field is not found. + /// public IReflectedMethod GetMethod(Type type, string name, bool required = true) { return this.AssertAccessAllowed( diff --git a/src/SMAPI/Framework/ModHelpers/TranslationHelper.cs b/src/SMAPI/Framework/ModHelpers/TranslationHelper.cs index be7768e8..a88ca9c9 100644 --- a/src/SMAPI/Framework/ModHelpers/TranslationHelper.cs +++ b/src/SMAPI/Framework/ModHelpers/TranslationHelper.cs @@ -16,10 +16,10 @@ namespace StardewModdingAPI.Framework.ModHelpers /********* ** Accessors *********/ - /// The current locale. + /// public string Locale => this.Translator.Locale; - /// The game's current language code. + /// public LocalizedContentManager.LanguageCode LocaleEnum => this.Translator.LocaleEnum; @@ -37,22 +37,19 @@ namespace StardewModdingAPI.Framework.ModHelpers this.Translator.SetLocale(locale, languageCode); } - /// Get all translations for the current locale. + /// public IEnumerable GetTranslations() { return this.Translator.GetTranslations(); } - /// Get a translation for the current locale. - /// The translation key. + /// public Translation Get(string key) { return this.Translator.Get(key); } - /// Get a translation for the current locale. - /// The translation key. - /// An object containing token key/value pairs. This can be an anonymous object (like new { value = 42, name = "Cranberries" }), a dictionary, or a class instance. + /// public Translation Get(string key, object tokens) { return this.Translator.Get(key, tokens); -- cgit