add documentation

Assets/Features/VoxelWorld/Contracts/NavMeshWorldContracts.cs

@@ -3,34 +3,88 @@ using UnityEngine;
 
 namespace InfiniteWorld.VoxelWorld.Contracts
 {
+    /// <summary>
+    /// Provides chunk-level nav build inputs without exposing the internal runtime representation of the voxel world.
+    /// </summary>
     public interface IChunkNavSourceReader
     {
+        /// <summary>
+        /// Returns the world-space edge length of one chunk so nav coverage and source collection can reason in chunk units.
+        /// </summary>
         float ChunkWorldSize { get; }
+
+        /// <summary>
+        /// Copies the coordinates of chunks that currently have usable nav geometry into the provided list.
+        /// </summary>
         void GetLoadedChunkCoords(List<Vector2Int> results);
+
+        /// <summary>
+        /// Retrieves the current nav source snapshot for a loaded chunk so sidecar systems can rebuild coverage from stable descriptors.
+        /// </summary>
         bool TryGetChunkNavSourceSnapshot(Vector2Int coord, out ChunkNavSourceSnapshot snapshot);
     }
 
+    /// <summary>
+    /// Exposes the current gameplay-relevant interest points that should influence world streaming or nav coverage planning.
+    /// </summary>
     public interface IWorldInterestReader
     {
+        /// <summary>
+        /// Increments when the logical set of interest points changes and downstream systems should invalidate cached plans.
+        /// </summary>
         int InterestVersion { get; }
+
+        /// <summary>
+        /// Appends the currently active interest points into the provided list.
+        /// </summary>
         void GetInterestPoints(List<WorldInterestPoint> results);
     }
 
+    /// <summary>
+    /// Exposes the currently built nav coverage so gameplay systems can query whether a world-space area is ready for pathing.
+    /// </summary>
     public interface INavCoverageReader
     {
+        /// <summary>
+        /// Returns whether the supplied world position lies inside ready nav coverage, not merely inside generated terrain.
+        /// </summary>
         bool IsPositionCovered(Vector3 worldPosition);
+
+        /// <summary>
+        /// Copies the currently active coverage windows so diagnostics and higher-level systems can inspect the coverage topology.
+        /// </summary>
         void GetCoverageWindows(List<NavCoverageWindowSnapshot> results);
     }
 
+    /// <summary>
+    /// Lets callers inject short-lived route hints that bias nav coverage planning toward an upcoming movement corridor.
+    /// </summary>
     public interface INavCoverageHintRegistry
     {
+        /// <summary>
+        /// Registers or refreshes a temporary linear hint for the given owner so coverage can prewarm along a route before pathing starts.
+        /// </summary>
         void SetLinearHint(int ownerId, Vector3 from, Vector3 to, float priority, float ttlSeconds);
+
+        /// <summary>
+        /// Removes the temporary hint owned by the caller when the route is no longer relevant.
+        /// </summary>
         void ClearHint(int ownerId);
     }
 
+    /// <summary>
+    /// Exposes the current set of transient nav coverage hints as read-only interest points for the nav coverage scheduler.
+    /// </summary>
     public interface INavCoverageHintReader
     {
+        /// <summary>
+        /// Increments whenever the effective hint set changes so dependent planners can invalidate cached coverage windows.
+        /// </summary>
         int HintVersion { get; }
+
+        /// <summary>
+        /// Appends the currently active transient hint points into the provided list.
+        /// </summary>
         void GetHintPoints(List<WorldInterestPoint> results);
     }
 }