Add XML documentation to Ryujinx.Graphics.Gpu.Memory

1 files changed, 80 insertions, 2 deletions

diff --git a/Ryujinx.Graphics.Gpu/Memory/RangeList.cs b/Ryujinx.Graphics.Gpu/Memory/RangeList.cs
index 45f23cf3..52bcf9b4 100644
--- a/Ryujinx.Graphics.Gpu/Memory/RangeList.cs
+++ b/Ryujinx.Graphics.Gpu/Memory/RangeList.cs
@@ -3,17 +3,28 @@ using System.Collections.Generic;
 
 namespace Ryujinx.Graphics.Gpu.Memory
 {
+    /// <summary>
+    /// Lists of GPU resources with data on guest memory.
+    /// </summary>
+    /// <typeparam name="T">Type of the GPU resource</typeparam>
     class RangeList<T> where T : IRange<T>
     {
         private const int ArrayGrowthSize = 32;
 
         private List<T> _items;
 
+        /// <summary>
+        /// Creates a new GPU resources list.
+        /// </summary>
         public RangeList()
         {
             _items = new List<T>();
         }
 
+        /// <summary>
+        /// Adds a new item to the list.
+        /// </summary>
+        /// <param name="item">The item to be added</param>
         public void Add(T item)
         {
             int index = BinarySearch(item.Address);
@@ -26,6 +37,11 @@ namespace Ryujinx.Graphics.Gpu.Memory
             _items.Insert(index, item);
         }
 
+        /// <summary>
+        /// Removes a item from the list.
+        /// </summary>
+        /// <param name="item">The item to be removed</param>
+        /// <returns>True if the item was removed, or false if it was not found</returns>
         public bool Remove(T item)
         {
             int index = BinarySearch(item.Address);
@@ -58,11 +74,26 @@ namespace Ryujinx.Graphics.Gpu.Memory
             return false;
         }
 
+        /// <summary>
+        /// Gets the first item on the list overlapping in memory with the specified item.
+        /// Despite the name, this has no ordering guarantees of the returned item.
+        /// It only ensures that the item returned overlaps the specified item.
+        /// </summary>
+        /// <param name="item">Item to check for overlaps</param>
+        /// <returns>The overlapping item, or the default value for the type if none found</returns>
         public T FindFirstOverlap(T item)
         {
             return FindFirstOverlap(item.Address, item.Size);
         }
 
+        /// <summary>
+        /// Gets the first item on the list overlapping the specified memory range.
+        /// Despite the name, this has no ordering guarantees of the returned item.
+        /// It only ensures that the item returned overlaps the specified memory range.
+        /// </summary>
+        /// <param name="address">Start address of the range</param>
+        /// <param name="size">Size in bytes or the rangee</param>
+        /// <returns>The overlapping item, or the default value for the type if none found</returns>
         public T FindFirstOverlap(ulong address, ulong size)
         {
             int index = BinarySearch(address, size);
@@ -75,11 +106,24 @@ namespace Ryujinx.Graphics.Gpu.Memory
             return _items[index];
         }
 
+        /// <summary>
+        /// Gets all items overlapping with the specified item in memory.
+        /// </summary>
+        /// <param name="item">Item to check for overlaps</param>
+        /// <param name="output">Output array where matches will be written. It is automatically resized to fit the results</param>
+        /// <returns>The number of overlapping items found</returns>
         public int FindOverlaps(T item, ref T[] output)
         {
             return FindOverlaps(item.Address, item.Size, ref output);
         }
 
+        /// <summary>
+        /// Gets all items on the list overlapping the specified memory range.
+        /// </summary>
+        /// <param name="address">Start address of the range</param>
+        /// <param name="size">Size in bytes or the rangee</param>
+        /// <param name="output">Output array where matches will be written. It is automatically resized to fit the results</param>
+        /// <returns>The number of overlapping items found</returns>
         public int FindOverlaps(ulong address, ulong size, ref T[] output)
         {
             int outputIndex = 0;
@@ -110,19 +154,36 @@ namespace Ryujinx.Graphics.Gpu.Memory
             return outputIndex;
         }
 
+        /// <summary>
+        /// Gets all items overlapping with the specified item in memory.
+        /// This method only returns correct results if none of the items on the list overlaps with
+        /// each other. If that is not the case, this method should not be used.
+        /// This method is faster than the regular method to find all overlaps.
+        /// </summary>
+        /// <param name="item">Item to check for overlaps</param>
+        /// <param name="output">Output array where matches will be written. It is automatically resized to fit the results</param>
+        /// <returns>The number of overlapping items found</returns>
         public int FindOverlapsNonOverlapping(T item, ref T[] output)
         {
             return FindOverlapsNonOverlapping(item.Address, item.Size, ref output);
         }
 
+        /// <summary>
+        /// Gets all items on the list overlapping the specified memory range.
+        /// This method only returns correct results if none of the items on the list overlaps with
+        /// each other. If that is not the case, this method should not be used.
+        /// This method is faster than the regular method to find all overlaps.
+        /// </summary>
+        /// <param name="address">Start address of the range</param>
+        /// <param name="size">Size in bytes or the rangee</param>
+        /// <param name="output">Output array where matches will be written. It is automatically resized to fit the results</param>
+        /// <returns>The number of overlapping items found</returns>
         public int FindOverlapsNonOverlapping(ulong address, ulong size, ref T[] output)
         {
             // This is a bit faster than FindOverlaps, but only works
             // when none of the items on the list overlaps with each other.
             int outputIndex = 0;
 
-            ulong endAddress = address + size;
-
             int index = BinarySearch(address, size);
 
             if (index >= 0)
@@ -147,6 +208,12 @@ namespace Ryujinx.Graphics.Gpu.Memory
             return outputIndex;
         }
 
+        /// <summary>
+        /// Gets all items on the list with the specified memory address.
+        /// </summary>
+        /// <param name="address">Address to find</param>
+        /// <param name="output">Output array where matches will be written. It is automatically resized to fit the results</param>
+        /// <returns>The number of matches found</returns>
         public int FindOverlaps(ulong address, ref T[] output)
         {
             int index = BinarySearch(address);
@@ -181,6 +248,11 @@ namespace Ryujinx.Graphics.Gpu.Memory
             return outputIndex;
         }
 
+        /// <summary>
+        /// Performs binary search on the internal list of items.
+        /// </summary>
+        /// <param name="address">Address to find</param>
+        /// <returns>List index of the item, or complement index of nearest item with lower value on the list</returns>
         private int BinarySearch(ulong address)
         {
             int left  = 0;
@@ -212,6 +284,12 @@ namespace Ryujinx.Graphics.Gpu.Memory
             return ~left;
         }
 
+        /// <summary>
+        /// Performs binary search for items overlapping a given memory range.
+        /// </summary>
+        /// <param name="address">Start address of the range</param>
+        /// <param name="size">Size of the range in bytes</param>
+        /// <returns>List index of the item, or complement index of nearest item with lower value on the list</returns>
         private int BinarySearch(ulong address, ulong size)
         {
             int left  = 0;