Merge pull request #806 from Miepee/documentation

First attempt at adding in-code documentation

UndertaleModCli/Program.UMTLibInherited.cs

@@ -57,7 +57,7 @@ public void EnsureDataLoaded()
                 throw new Exception("No data file is loaded.");
         }
 
-        public async Task<bool> Make_New_File()
+        public async Task<bool> MakeNewDataFile()
         {
             // This call has no use except to suppress the "method is not doing anything async" warning
             await Task.Delay(1);
@@ -261,17 +261,17 @@ public void AddProgress(int amount)
             progressValue += amount;
         }
 
-        public void IncProgress()
+        public void IncrementProgress()
         {
             progressValue++;
         }
 
-        public void AddProgressP(int amount) //P - Parallel (multithreaded)
+        public void AddProgressParallel(int amount) //P - Parallel (multithreaded)
         {
             Interlocked.Add(ref progressValue, amount); //thread-safe add operation (not the same as "lock ()")
         }
 
-        public void IncProgressP()
+        public void IncrementProgressParallel()
         {
             Interlocked.Increment(ref progressValue); //thread-safe increment
         }
@@ -334,14 +334,14 @@ public void SyncBinding(string resourceType, bool enable)
             //there is no UI with any data binding
         }
 
-        public void SyncBinding(bool enable = false)
+        public void DisableAllSyncBindings()
         {
             //there is no UI with any data binding
         }
 
         #endregion
 
-        public void StartUpdater()
+        public void StartProgressBarUpdater()
         {
             if (cTokenSource is not null)
                 Console.WriteLine("Warning - there is another progress updater task running (hangs) in the background.");
@@ -351,7 +351,7 @@ public void StartUpdater()
 
             updater = Task.Run(ProgressUpdater);
         }
-        public async Task StopUpdater() //"async" because "Wait()" blocks UI thread
+        public async Task StopProgressBarUpdater() //"async" because "Wait()" blocks UI thread
         {
             if (cTokenSource is null) return;
 
@@ -376,7 +376,7 @@ public void ChangeSelection(object newSelection)
             Selected = newSelection;
         }
 
-        public string PromptChooseDirectory(string prompt)
+        public string PromptChooseDirectory()
         {
             string path;
             DirectoryInfo directoryInfo;
@@ -504,11 +504,11 @@ public string SimpleTextInput(string title, string label, string defaultValue, b
             return result;
         }
 
-        public async Task ClickableTextOutput(string title, string query, int resultsCount, IOrderedEnumerable<KeyValuePair<string, List<string>>> resultsDict, bool editorDecompile, IOrderedEnumerable<string> failedList = null)
+        public async Task ClickableSearchOutput(string title, string query, int resultsCount, IOrderedEnumerable<KeyValuePair<string, List<string>>> resultsDict, bool editorDecompile, IOrderedEnumerable<string> failedList = null)
         {
-            await ClickableTextOutput(title, query, resultsCount, resultsDict.ToDictionary(pair => pair.Key, pair => pair.Value), editorDecompile, failedList);
+            await ClickableSearchOutput(title, query, resultsCount, resultsDict.ToDictionary(pair => pair.Key, pair => pair.Value), editorDecompile, failedList);
         }
-        public async Task ClickableTextOutput(string title, string query, int resultsCount, IDictionary<string, List<string>> resultsDict, bool editorDecompile, IEnumerable<string> failedList = null)
+        public async Task ClickableSearchOutput(string title, string query, int resultsCount, IDictionary<string, List<string>> resultsDict, bool editorDecompile, IEnumerable<string> failedList = null)
         {
             await Task.Delay(1); //dummy await
 

UndertaleModCli/Program.cs

@@ -492,6 +492,7 @@ private static UndertaleData ReadDataFile(FileInfo datafile, WarningHandlerDeleg
         /// <returns>A new <see cref="String"/> that can be directly passed onto a FileInfo Constructor</returns>
         //TODO: needs some proper testing on how it behaves on Linux/MacOS and might need to get expanded
         private static string RemoveQuotes(string s)
+
         {
             return s.TrimStart('"').TrimEnd('"');
         }

UndertaleModCli/UndertaleModCli.csproj

@@ -8,6 +8,7 @@
 	<Nullable>annotations</Nullable>
 	<RollForward>LatestMajor</RollForward>
 	<PackageVersion>1.0.0</PackageVersion>
+	<GenerateDocumentationFile>True</GenerateDocumentationFile>
   </PropertyGroup>
 
   <ItemGroup>

UndertaleModLib/AumiIPC.cs

@@ -10,7 +10,39 @@ namespace UndertaleModLib
 {
     public struct IpcMessage_t
     {
+        /// <summary>
+        /// A numerical value (1 to 4 for the latest AUMI implementation).
+        /// </summary>
+        /// <remarks>
+        ///  The following table describes and explains the numerical values:
+        /// <list type="table">
+        ///     <listheader>
+        ///         <term>number</term>
+        ///         <description>Explanation</description>
+        ///     </listheader>
+        ///     <item>
+        ///         <term>1</term>
+        ///         <description>Test Communication - Always returns a string that's 128 characters long.</description>
+        ///     </item>
+        ///     <item>
+        ///         <term>2</term>
+        ///         <description>Get Function By Index - Returns information about a function at a specified index in the runner.</description>
+        ///     </item>
+        ///     <item>
+        ///         <term>3</term>
+        ///         <description>Get Function By Name - Returns information about a function with a specified name.</description>
+        ///     </item>
+        ///     <item>
+        ///         <term>4</term>
+        ///         <description>Execute Code - Executes precompiled bytecode in the global context.</description>
+        ///     </item>
+        /// </list>
+        /// </remarks>
         public short FuncID;
+
+        /// <summary>
+        /// A 512 byte buffer containing information which accompanies <see cref="FuncID"/>.
+        /// </summary>
         [MarshalAs(UnmanagedType.ByValArray, SizeConst = 512)]
         public byte[] Buffer;
 
@@ -30,7 +62,15 @@ public byte[] RawBytes()
 
     public struct IpcReply_t
     {
+        /// <summary>
+        /// A numerical value from 0 to n, where 0 means success.
+        /// </summary>
+        /// <remarks>Anything other than 0 means failure, where the number specifies the actual reason.</remarks>
         public int AUMIResult; // Always contains a value.
+
+        /// <summary>
+        /// A 128 byte buffer, might not always be filled in.
+        /// </summary>
         [MarshalAs(UnmanagedType.ByValArray, SizeConst = 128)]
         public byte[] Buffer;
 

UndertaleModLib/Compiler/BuiltinList.cs

@@ -105,9 +105,10 @@ public AccessorInfo(string lFunc, string lPreFunc, string lPostFunc, string rFun
         }
     }
 
-    // This is a really long list of known constants and variables, taken from code analysis
-    // This deserves to be in its own file for that reason...
-    // This will likely need to be updated with every new GameMaker version with new features
+    /// <summary>
+    /// A really long list of known Game Maker: Studio constants and variables, taken from code analysis. <br/>
+    /// Will likely need to be updated on every new Game Maker version with new features.
+    /// </summary>
     public class BuiltinList
     {
         public Dictionary<string, double> Constants = null;
@@ -132,7 +133,7 @@ public BuiltinList(UndertaleData data)
         {
             Initialize(data);
         }
-        
+
         public void Initialize(UndertaleData data)
         {
             // Functions

UndertaleModLib/Models/UndertaleAnimationCurve.cs

@@ -7,6 +7,9 @@
 
 namespace UndertaleModLib.Models
 {
+    /// <summary>
+    /// An animation curve entry in a data file.
+    /// </summary>
     [PropertyChanged.AddINotifyPropertyChangedInterface]
     public class UndertaleAnimationCurve : UndertaleNamedResource
     {
@@ -16,15 +19,29 @@ public enum GraphTypeEnum : uint
             Unknown1 = 1
         }
 
+        /// <summary>
+        /// The name of this animation curve.
+        /// </summary>
         public UndertaleString Name { get; set; }
+
+        /// <summary>
+        /// The graph type of this animation curve.
+        /// </summary>
         public GraphTypeEnum GraphType { get; set; }
+
+
         public UndertaleSimpleList<Channel> Channels { get; set; }
 
         public void Serialize(UndertaleWriter writer)
         {
             Serialize(writer, true);
         }
 
+        /// <summary>
+        /// Serializes the data file into a specified <see cref="UndertaleWriter"/>.
+        /// </summary>
+        /// <param name="writer">Where to serialize to.</param>
+        /// <param name="includeName">Whether to include <see cref="Name"/> in the serialization.</param>
         public void Serialize(UndertaleWriter writer, bool includeName)
         {
             if (includeName)
@@ -38,6 +55,11 @@ public void Unserialize(UndertaleReader reader)
             Unserialize(reader, true);
         }
 
+        /// <summary>
+        /// Deserializes from a specified <see cref="UndertaleReader"/> to the current data file.
+        /// </summary>
+        /// <param name="reader">Where to deserialize from.</param>
+        /// <param name="includeName">Whether to include <see cref="Name"/> in the deserialization.</param>
         public void Unserialize(UndertaleReader reader, bool includeName)
         {
             if (includeName)

UndertaleModLib/Models/UndertaleBackground.cs

@@ -8,13 +8,24 @@
 
 namespace UndertaleModLib.Models
 {
+    /// <summary>
+    /// A background or tileset entry in a data file.
+    /// </summary>
+    /// <remarks>For Game Maker Studio: 2, this will only ever be a tileset. For Game Maker Studio: 1, this is usually a background,
+    /// but is sometimes repurposed as use for a tileset as well.</remarks>
     [PropertyChanged.AddINotifyPropertyChangedInterface]
     public class UndertaleBackground : UndertaleNamedResource
     {
+        /// <summary>
+        /// A tile id, which can be used for referencing specific tiles in a tileset. Game Maker Studio 2 only.
+        /// </summary>
         public class TileID : UndertaleObject, INotifyPropertyChanged
         {
             private uint _ID;
 
+            /// <summary>
+            /// The id of a specific tile.
+            /// </summary>
             public uint ID { get => _ID; set { _ID = value; PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(nameof(ID))); } }
 
             public event PropertyChangedEventHandler PropertyChanged;
@@ -30,21 +41,85 @@ public void Unserialize(UndertaleReader reader)
             }
         }
 
+        /// <summary>
+        /// The name of the background.
+        /// </summary>
         public UndertaleString Name { get; set; }
+
+        /// <summary>
+        /// Whether the background should be transparent.
+        /// </summary>
         public bool Transparent { get; set; }
+
+        /// <summary>
+        /// Whether the background should get smoothed.
+        /// </summary>
         public bool Smooth { get; set; }
+
+        /// <summary>
+        /// Whether to preload the background.
+        /// </summary>
         public bool Preload { get; set; }
+
+        /// <summary>
+        /// The <see cref="UndertaleTexturePageItem"/> this background uses.
+        /// </summary>
         public UndertaleTexturePageItem Texture { get; set; }
+
+
+        /// <summary>
+        /// TODO: Functionality currently unknown.
+        /// </summary>
         public uint GMS2UnknownAlways2 { get; set; } = 2;
+
+        /// <summary>
+        /// The tile width of the tileset. Game Maker Studio 2 only.
+        /// </summary>
         public uint GMS2TileWidth { get; set; } = 32;
+
+        /// <summary>
+        /// The tile height of the tileset. Game Maker Studio 2 only.
+        /// </summary>
         public uint GMS2TileHeight { get; set; } = 32;
+
+        /// <summary>
+        /// The output border X of the tileset. Game Maker Studio 2 only.
+        /// </summary>
         public uint GMS2OutputBorderX { get; set; } = 2;
+
+        /// <summary>
+        /// The output Border Y of the tileset. Game Maker Studio 2 only.
+        /// </summary>
         public uint GMS2OutputBorderY { get; set; } = 2;
+
+        /// <summary>
+        /// The amount of columns this tileset has.
+        /// </summary>
         public uint GMS2TileColumns { get; set; } = 32;
+
+        /// <summary>
+        /// The number of frames of the tileset animation.
+        /// </summary>
         public uint GMS2ItemsPerTileCount { get; set; } = 1;
+
+        /// <summary>
+        /// The amount of tiles this tileset has.
+        /// </summary>
         public uint GMS2TileCount { get; set; } = 1024;
+
+        /// <summary>
+        /// TODO: Functionality currently unknown.
+        /// </summary>
         public uint GMS2UnknownAlwaysZero { get; set; } = 0;
-        public long GMS2FrameLength { get; set; } = 66666; // time for each frame (in microseconds seemingly)
+
+        /// <summary>
+        /// The time for each frame in microseconds.
+        /// </summary>
+        public long GMS2FrameLength { get; set; } = 66666;
+
+        /// <summary>
+        /// All tile ids of this tileset. Game Maker Studio 2 only.
+        /// </summary>
         public List<TileID> GMS2TileIds { get; set; } = new List<TileID>();
 
         public void Serialize(UndertaleWriter writer)