phase(N.1): document LandBlock length-81 invariant on adapter

Addresses code-review feedback on commit 26cf2b8. The dropped
ArgumentException length guards were correct to drop because
DatReaderWriter.LandBlock self-initializes Terrain[] and Height[]
to length 81 in its constructor — but that invariant was not
documented anywhere visible to future readers. Adds an XML doc
<remarks> block explaining the guarantee so callers constructing
synthetic LandBlocks know what to expect.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Erik 2026-05-08 09:20:53 +02:00
parent 26cf2b84e7
commit 91fd9de3f6

View file

@ -25,6 +25,16 @@ internal static class WbSceneryAdapter
/// <c>TerrainInfo.Scenery</c> (bits 11-15) → <see cref="TerrainEntry.Scenery"/>
/// <c>LandBlock.Height[i]</c> → <see cref="TerrainEntry.Height"/>
/// </summary>
/// <remarks>
/// No runtime length guards are needed here because
/// <c>DatReaderWriter.DBObjs.LandBlock</c>'s default constructor
/// self-initializes both <c>Terrain</c> and <c>Height</c> to fixed-length
/// arrays of exactly 81 elements (9×9 vertices per landblock). Any caller
/// that constructs a synthetic <see cref="LandBlock"/> with partial arrays
/// will receive an <see cref="IndexOutOfRangeException"/> at the first
/// mis-sized index, which is the correct fast-fail behaviour for a
/// contract violation of this kind.
/// </remarks>
public static TerrainEntry[] BuildTerrainEntries(LandBlock block)
{
ArgumentNullException.ThrowIfNull(block);