merged in line with internal master branch

README.md

@@ -1,14 +1,15 @@
+# <a href="https://www.youtube.com/watch?v=pmECrkdzHzQ">Watch the video tutorial</a>
+<a href="https://www.youtube.com/watch?v=pmECrkdzHzQ"><img src="https://img.youtube.com/vi/pmECrkdzHzQ/0.jpg" alt="mod.io" width="420"/></a>
+
 <a href="https://mod.io"><img src="https://beta.mod.io/images/branding/modio_logo_bluewhite.svg" alt="mod.io" width="360" align="right"/></a>
-# mod.io Unity Plugin
-[![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://github.com/modio/modio-unity/blob/main/LICENSE.md)
+# Mod.io Unity Plugin
+[![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://github.com/modio/modio-unity/blob/master/LICENSE)
 [![Discord](https://img.shields.io/discord/389039439487434752.svg?label=Discord&logo=discord&color=7289DA&labelColor=2C2F33)](https://discord.mod.io)
 [![Master docs](https://img.shields.io/badge/docs-master-green.svg)](https://github.com/modio/modio-unity-v2/wiki)
 [![Unity 3D](https://img.shields.io/badge/Unity-2018.4+-lightgrey.svg)](https://unity3d.com)
 
 ## Installation
-
-### <a href="https://www.youtube.com/watch?v=pmECrkdzHzQ">Watch the video tutorial</a>
-<a href="https://www.youtube.com/watch?v=pmECrkdzHzQ"><img src="https://img.youtube.com/vi/pmECrkdzHzQ/0.jpg" alt="mod.io" width="420"/></a>
+Requires **Unity 2018.4** or later. Tested on Windows, and MacOS.
 
 ### Git Repository or .unitypackage
 You can import the plugin directly from the [Unity Asset Store](https://assetstore.unity.com/packages/tools/integration/mod-browser-manager-by-mod-io-138866), or by downloading the package directly from the [Releases page](https://github.com/modio/modio-unity/releases). If you have any previous versions of the plugin installed, it is highly recommended to delete them before importing a newer version.
@@ -20,9 +21,9 @@ Alternatively, you can download an archive of the code using GitHub's download f
 1. Set up your [game profile on mod.io](https://mod.io/games/add) (or our [private test environment](https://test.mod.io/games/add)) to get your game ID and API key. 
 2. Add the plugin to your project using the installation instructions above.
 3. Ensure you dont have any conflicting libraries by going to Assets/Plugins/mod.io/ThirdParty to remove any libraries you may already have in your project (such as JsonNet).
-4. Restart Unity to ensure it recognises the new assembly definitions.
+4. Restart unity to ensure it recognises the new assembly definitions.
 5. Go to Tools > mod.io > Edit Settings to locate the config file.
-6. Select the config file and use the inspector to assign your game ID and API key in server settings (Make sure to deselect the config file before using playmode in the editor. A known Unity bug can cause the editor to crash in 2019-2021).
+6. Select the config file and use the inspector to assign your game ID and API key in server settings (Make sure to deselect the config file before using playmode in the editor. A known unity bug can cause the editor to crash in 2019-2021).
 7. Setup complete! Join us [on Discord](https://discord.mod.io) if you have any questions or need help.
 
 ## Setting up the Browser UI
@@ -40,23 +41,23 @@ In the current version of the plugin it is required that a user session is authe
 
 
 ## Usage
-Below are a couple examples for some of the common usages of the plugin. Such as initialising, authenticating, enabling automatic downloads and installs, and getting a few mods from the mod.io server.
+below are a couple examples for some of the common usages of the plugin. Such as initialising, authenticating, enabling automatic downloads and installs, and getting a few mods from the mod.io server.
 
 All of the methods required to use the plugin can be found in ModIOUnity.cs. If you prefer using async methods over callbacks you can alternatively use ModIOUnityAsync.cs to use an async variation of the same methods.
 
-### Initialize the plugin
+### Initialise the plugin
 ```javascript
-void async Example()
+async void Example()
 {
-    Result result = await ModIOUnityAsync.InitializeForUserAsync("ExampleUser");
+    Result result = await ModIOUnityAsync.InitializeForUser("ExampleUser");
 
     if (result.Succeeded())
     {
-        Debug.Log("Initialized plugin");
+        Debug.Log("Initialised plugin");
     }
     else
     {
-        Debug.Log("Failed to initialize plugin");
+        Debug.Log("Failed to initialise plugin");
     {
 }
 ```
@@ -96,7 +97,7 @@ void Example()
 }
 
 // The following method will get invoked whenever an event concerning mod management occurs
-void ModManagementDelegate(ModManagementEventType eventType, ModId modId)
+void ModManagementDelegate(ModManagementEventType eventType, ModId modId, Result result)
 {
     Debug.Log("a mod management event of type " + eventType.ToString() + " has been invoked");
 }
@@ -105,7 +106,7 @@ void ModManagementDelegate(ModManagementEventType eventType, ModId modId)
 ### Authenticate a user
 In the current version of the plugin it is required that a user session is authenticated in order to subscribe and download mods. You can accomplish this with an email address or through another third party service, such as Steam or Google. Below is an example of how to do this from an email address provided by the user. A security code will be sent to their email account and can be used to authenticate (The plugin will cache the session token to avoid having to re-authenticate every time they run the application).
 ```javascript
-void async RequestEmailCode()
+async void RequestEmailCode()
 {
     Result result = await ModIOUnityAsync.RequestAuthenticationEmail("johndoe@gmail.com");
 
@@ -119,7 +120,7 @@ void async RequestEmailCode()
     }
 }
 
-void async SubmitCode(string userSecurityCode)
+async void SubmitCode(string userSecurityCode)
 {
     Result result = await ModIOUnityAsync.SubmitEmailSecurityCode(userSecurityCode);
 
@@ -136,7 +137,7 @@ void async SubmitCode(string userSecurityCode)
 
 ### Get Mod profiles from the mod.io server
 ```javascript
-void async Example()
+async void Example()
 {
     // create a filter to retreive the first ten mods for your game
     SearchFilter filter = new SearchFilter();
@@ -147,7 +148,7 @@ void async Example()
 
     if (response.result.Succeeded())
     {
-        Debug.Log("ModPage has " + response.value.mods.Length + " mods");
+        Debug.Log("ModPage has " + response.value.modProfiles.Length + " mods");
     }
     else
     {
@@ -156,7 +157,7 @@ void async Example()
 }
 ```
 
-## Submitting mods
+##Submitting mods
 You can also submit mods directly from the plugin. Refer to the documentation for methods such as ModIOUnity.CreateModProfile and ModIOUnity.UploadModfile.
 
 Users can also submit mods directly from the mod.io website by going to your game profile page. Simply create an account and upload mods directly.
@@ -180,7 +181,7 @@ mod.io offers the same core functionality as Steamworks Workshop (1 click mod in
 A private white label option is available to license, if you want a fully featured mod-platform that you can control and host in-house. [Contact us](mailto:developers@mod.io?subject=Whitelabel) to discuss.
 
 ## Contributions Welcome
-Our Unity plugin is public and open source. Game developers are welcome to utilize it directly, to add support for mods in their games, or fork it for their games customized use.
+Our Unity plugin is public and open source. Game developers are welcome to utilize it directly, to add support for mods in their games, or fork it for their games customized use. Want to make changes to our plugin? Submit a pull request with your recommended changes to be reviewed.
 
 ## Other Repositories
 Our aim with [mod.io](https://mod.io), is to provide an [open modding API](https://docs.mod.io). You are welcome to [view, fork and contribute to our other codebases](https://github.com/modio) in use.

Runtime/Classes/CreationToken.cs

@@ -1,6 +1,13 @@
 
 namespace ModIO
 {
+    /// <summary>
+    /// This is used with creating new mod profiles. Using a token ensures you dont
+    /// create duplicate profiles.
+    /// </summary>
+    /// <seealso cref="ModIOUnity.GenerateCreationToken"/>
+    /// <seealso cref="ModIOUnityAsync.CreateModProfile"/>
+    /// <seealso cref="ModIOUnity.CreateModProfile"/>
     public class CreationToken
     {
         string creationTokenFileHash;

Runtime/Classes/ModProfileDetails.cs

@@ -9,6 +9,8 @@ namespace ModIO
     /// summary, otherwise the submission will be rejected (All fields except modId are optional if
     /// submitting this via EditModProfile)
     /// </summary>
+    /// <seealso cref="ModIOUnity.CreateModProfile"/>
+    /// <seealso cref="ModIOUnity.EditModProfile"/>
     public class ModProfileDetails
     {
         /// <summary>

Runtime/Classes/SearchFilter.cs

@@ -6,12 +6,15 @@ namespace ModIO
     /// <summary>
     /// Used to build a filter that is sent with requests for retrieving mods.
     /// </summary>
+    /// <seealso cref="ModIOUnity.GetMods"/>
+    /// <seealso cref="ModIOUnityAsync.GetMods"/>
     public class SearchFilter
     {
         bool hasPageIndexBeenSet = false;
         bool hasPageSizeBeenSet = false;
 
 #region Endpoint Parameters
+        // These are for internal use. Do not use
         internal string sortFieldName = string.Empty;
         internal bool isSortAscending = true;
         internal SortModsBy sortBy = SortModsBy.DateSubmitted;
@@ -20,39 +23,84 @@ public class SearchFilter
         internal List<string> searchPhrases = new List<string>();
         internal List<string> tags = new List<string>();
 #endregion
-
+        /// <summary>
+        /// Adds a phrase into the filter to be used when filtering mods in a request.
+        /// </summary>
+        /// <param name="phrase">the string to be added to the filter</param>
         public void AddSearchPhrase(string phrase)
         {
             searchPhrases.Add(phrase);
         }
 
+        /// <summary>
+        /// Adds a tag to be used in filtering mods for a request.
+        /// </summary>
+        /// <param name="tag">the tag to be added to the filter</param>
+        /// <seealso cref="Tag"/>
+        /// <seealso cref="TagCategory"/>
         public void AddTag(string tag)
         {
             tags.Add(tag);
         }
 
+        /// <summary>
+        /// Determines what category mods should be sorted and returned by. eg if the category
+        /// SortModsBy.Downloads was used, then the results would be returned by the number of
+        /// downloads. Depending on the Ascending or Descending setting, it will start or end with
+        /// mods that have the highest or lowest number of downloads.
+        /// </summary>
+        /// <param name="category">the category to sort the request</param>
+        /// <seealso cref="SetToAscending"/>
         public void SortBy(SortModsBy category)
         {
             sortBy = category;
         }
 
+        /// <summary>
+        /// Determines the order of the results being returned. eg should results be filtered from
+        /// highest to lowest, or lowest to highest.
+        /// </summary>
+        /// <param name="isAscending"></param>
         public void SetToAscending(bool isAscending)
         {
             isSortAscending = isAscending;
         }
 
+        /// <summary>
+        /// Sets the zero based index of the page. eg if there are 1,000 results based on the filter
+        /// settings provided, and the page size is 100. Setting this to 1 will return the mods from
+        /// 100-200. Whereas setting this to 0 will return the first 100 results.
+        /// </summary>
+        /// <param name="pageIndex"></param>
+        /// <seealso cref="SetPageSize"/>
         public void SetPageIndex(int pageIndex)
         {
             this.pageIndex = pageIndex;
             hasPageIndexBeenSet = true;
         }
 
+        /// <summary>
+        /// Sets the maximum page size of the request. eg if there are 50 results and the index is
+        /// set to 0. If the page size is set to 10 you will receive the first 10 results. If the
+        /// page size is set to 100 you will only receive the total 50 results, because there are
+        /// no more to be got.
+        /// </summary>
+        /// <param name="pageSize"></param>
+        /// <seealso cref="SetPageIndex"/>
         public void SetPageSize(int pageSize)
         {
             this.pageSize = pageSize;
             hasPageSizeBeenSet = true;
         }
 
+        /// <summary>
+        /// You can use this method to check if a search filter is setup correctly before using it
+        /// in a GetMods request.
+        /// </summary>
+        /// <param name="result"></param>
+        /// <returns>true if the filter is valid</returns>
+        /// <seealso cref="ModIOUnity.GetMods"/>
+        /// <seealso cref="ModIOUnityAsync.GetMods"/>
         public bool IsSearchFilterValid(out Result result)
         {
             bool paginationSet = hasPageIndexBeenSet && hasPageSizeBeenSet;
@@ -62,14 +110,13 @@ public bool IsSearchFilterValid(out Result result)
             // TODO Check if tags are correct? Or will they just get ignored?
             // ^ Perhaps log a warning if non-fatal
 
-
             if(!paginationSet)
             {
                 result = ResultBuilder.Create(ResultCode.InvalidParameter_PaginationParams);
                 Logger.Log(
                     LogLevel.Error,
                     "The pagination parameters haven't been set for this filter. Make sure to "
-                        + "use SetPage(int) and SetPageSize(int) before using a filter.");
+                        + "use SetPageIndex(int) and SetPageSize(int) before using a filter.");
             }
             else
             {

Runtime/Enums/LogLevel.cs

@@ -1,5 +1,9 @@
 namespace ModIO
 {
+    /// <summary>
+    /// The logging level of the plugin. Used in BuildSettings to determine which log messages to
+    /// ignore or display.
+    /// </summary>
     public enum LogLevel
     {
         None = -1,

Runtime/Enums/ModStatus.cs

@@ -2,8 +2,8 @@
 {
     public enum ModStatus
     {
-        Accepted,
-        NotAccepted,
-        Deleted
+        Accepted = 0,
+        NotAccepted = 1,
+        Deleted = 3
     }
 }

Runtime/Enums/SortModsBy.cs

@@ -1,6 +1,13 @@
 
 namespace ModIO
 {
+    /// <summary>
+    /// Category to be used in the SearchFilter for determining how mods should be filtered in a
+    /// request.
+    /// </summary>
+    /// <seealso cref="SearchFilter"/>
+    /// <seealso cref="ModIOUnity.GetMods"/>
+    /// <seealso cref="ModIOUnityAsync.GetMods"/>
     public enum SortModsBy
     {
         Name,

Runtime/Enums/SubscribedModStatus.cs

@@ -1,5 +1,10 @@
 namespace ModIO
 {
+    /// <summary>
+    /// The current state of a subscribed mod. Useful for checking whether or not a mod has been
+    /// installed yet or if there was a problem trying to download/install it.
+    /// </summary>
+    /// <seealso cref="SubscribedMod"/>
     public enum SubscribedModStatus
     {
         Installed,

Runtime/Enums/UserPortal.cs

@@ -1,6 +1,10 @@
 namespace ModIO
 {
-    /// <summary>Values representing the valid User Portals that mod.io works with.</summary>
+    /// <summary>
+    /// Values representing the valid User Portals that mod.io works with.
+    /// Used when setting up BuildSettings.
+    /// </summary>
+    /// <seealso cref="BuildSettings"/>
     public enum UserPortal
     {
         None = 0,

Runtime/ModIO.Implementation/Classes/ModIOUnityImplementation.cs

@@ -61,8 +61,8 @@ public static bool IsInitialized(out Result result)
                 Logger.Log(
                     LogLevel.Error,
                     "You attempted to use a method but the plugin hasn't been initialized yet."
-                    + " Be sure to use ModIOUnity.InitializeForUserAsync to initialize the plugin "
-                    + "before attempting this method again.");
+                    + " Be sure to use ModIOUnity.InitializeForUser to initialize the plugin "
+                    + "before attempting this method again (Or ModIOUnityAsync.InitializeForUser).");
                 return false;
             }
         }

Runtime/ModIO.Implementation/Implementation.API/Classes/RESTAPI.cs

@@ -73,7 +73,7 @@ public static T DeserializeResponse<T>(string response, out Result result)
                     LogLevel.Error,
                     $"Failed to deserialize a response from the mod.io server. The data"
                         + $" may have been corrupted or isnt a valid Json format.\n\n[JsonUtility:"
-                        + $" {e.Message}] - Raw Response: {response}");
+                        + $" {e.Message}] - {e.InnerException} - Raw Response: {response}");
                 return default;
             }
         }