Documenting how FindInRing differs from GetTilesWithinRankDistance

Author: stavrosfa

C7Engine/C7GameData/Tile.cs

@@ -616,6 +616,28 @@ public Tile GetTileAtNeighborIndex(int neighborIndex) {
 			return map.tileAt(XCoordinate + xDelta, YCoordinate + yDelta);
 		}
 
+
+		/// <summary>
+		/// <para>
+		/// Walks clockwise/counter-clockwise the nth ring around
+		/// the specified tile starting on the northmost tile
+		/// and tries to find the first tile that matches our boolean criterion.
+		/// </para>
+		/// <para>
+		/// This differs from <see cref="GetTilesWithinRankDistance"/>,
+		/// because it includes all the tiles regardless of the distance.
+		/// An example would be that GetTilesWithinRankDistance() with a rank of 2
+		/// will not return a NN, SS, WW, or EE tile, whereas this method will.
+		/// </para>
+		/// <para>
+		/// It is mostly used to calculate to whom we should assign tiles
+		/// that are being claimed by more than 1 city or civilization.
+		/// </para>
+		/// </summary>
+		/// <param name="rank"></param>
+		/// <param name="predicate"></param>
+		/// <param name="clockwise"></param>
+		/// <returns></returns>
 		public Tile FindInRing(int rank, Func<Tile, bool> predicate, bool clockwise = true) {
 			Tile startingTile = map.tileAt(this.XCoordinate, this.YCoordinate - (2 * rank));