コーディング規約の検査ツールを追加し、禁止記法と doc コメント漏れを直す

spec/tools/check_comments.py を追加した。コメントと禁止記法の規約適合を
機械で確かめる。人手のレビューでは5言語ぶんの書きぶりを揃え続けられない。

検査するもの:
- 公開型・公開メソッドの doc コメント（言語ごとの形式）
- 条件分岐とループの説明コメント
- 禁止記法（三項演算子・オプショナルチェーン・null 合体演算子）

引数検証などのガード節は条件分岐の対象から外す。書いても
「不正なら弾く」としか書けず、かえって読みにくいため。
ブロック内の先頭に置いたコメントも、意図の説明として認める。

直したもの:
- C# のオプショナルチェーン 9 箇所を if で明示する形へ（規約で全面禁止）
- TypeScript のクラス 7 件に doc コメントを追加。
  ファイル冒頭のモジュール説明はあったが、IDE の補完はクラス直前しか拾わない
- TypeScript の setter 6 件と内部メソッド 3 件に doc コメントを追加
- Python の docstring 漏れ 9 件を追加

残りは条件分岐とループのコメント 329 件。件数が多く、機械的に埋めると
意味のないコメントを量産するので、別途進める。

Author: tatuharu

csharp/src/SpringNBTLibrary/World/Chunk.cs

@@ -176,7 +176,11 @@ private void CheckDataVersion(ChunkReadOptions options)
 
         if (options.OnVersionMismatch == VersionMismatchAction.Warn)
         {
-            options.OnWarning?.Invoke(message);
+            // 通知先が設定されているときだけ知らせる
+            if (options.OnWarning is not null)
+            {
+                options.OnWarning.Invoke(message);
+            }
         }
     }
 

csharp/src/SpringNBTLibrary/World/ChunkSection.cs

@@ -85,7 +85,15 @@ public NbtCompound ToNbt()
     /// <summary>使われていないパレット要素を取り除く。</summary>
     public void Compact()
     {
-        BlockStates?.Compact();
-        Biomes?.Compact();
+        // 持っているコンテナだけを掃除する
+        if (BlockStates is not null)
+        {
+            BlockStates.Compact();
+        }
+
+        if (Biomes is not null)
+        {
+            Biomes.Compact();
+        }
     }
 }

csharp/src/SpringNBTLibrary/World/Dimension.cs

@@ -224,9 +224,14 @@ public void Flush()
         }
 
         modifiedChunks.Clear();
-        regions?.Flush();
-        entities?.Flush();
-        poi?.Flush();
+        // 開いているフォルダだけを書き出す
+        foreach (RegionFolder? folder in new[] { regions, entities, poi })
+        {
+            if (folder is not null)
+            {
+                folder.Flush();
+            }
+        }
     }
 
     /// <summary>変更を書き戻してから閉じる。</summary>
@@ -242,9 +247,14 @@ public void Close()
             Flush();
         }
 
-        regions?.Close();
-        entities?.Close();
-        poi?.Close();
+        // 開いているフォルダだけを閉じる
+        foreach (RegionFolder? folder in new[] { regions, entities, poi })
+        {
+            if (folder is not null)
+            {
+                folder.Close();
+            }
+        }
         chunkCache.Clear();
         closed = true;
     }

python/src/spring_nbt_library/nbt/io.py

@@ -135,6 +135,7 @@ def _remaining(self) -> int:
         return len(self._data) - self._position
 
     def read_root(self, fmt: NbtFormat) -> NamedTag:
+        """ルートタグを 1 つ読む。形式によって名前の有無が変わる。"""
         tag_type = TagType.from_id(self._read_byte())
 
         # Java版のファイル形式でもネットワーク形式でも、ルートは必ず TAG_Compound
@@ -352,6 +353,7 @@ def __init__(self) -> None:
         self._buffer = bytearray()
 
     def write_root(self, named: NamedTag, fmt: NbtFormat) -> bytes:
+        """ルートタグを 1 つ書き出す。形式によって名前の有無が変わる。"""
         self._buffer.append(TagType.COMPOUND.value)
 
         if fmt == NbtFormat.JAVA:

python/src/spring_nbt_library/nbt/snbt.py

@@ -76,6 +76,7 @@ def __init__(self, text: str) -> None:
         self._position = 0
 
     def parse_whole(self) -> NbtTag:
+        """入力全体を 1 つのタグとして読む。末尾に余りがあればエラーにする。"""
         value = self._parse_value()
         self._skip_whitespace()
 

python/src/spring_nbt_library/nbt/tag.py

@@ -119,12 +119,14 @@ def value(self):
 
     @value.setter
     def value(self, new_value) -> None:
+        """値を差し替える。範囲外なら INVALID_ARGUMENT。"""
         self._value = self._validate(new_value)
 
     def _validate(self, value):
         raise NotImplementedError
 
     def clone(self) -> "NbtTag":
+        """同じ値を持つ新しいタグを作る。"""
         return type(self)(self._value)
 
     def __eq__(self, other) -> bool:
@@ -260,6 +262,7 @@ def value(self) -> List[int]:
 
     @value.setter
     def value(self, new_value) -> None:
+        """値を差し替える。範囲外なら INVALID_ARGUMENT。"""
         self._value = self._validate(new_value)
 
     def _validate(self, value) -> List[int]:
@@ -272,6 +275,7 @@ def _validate(self, value) -> List[int]:
         return result
 
     def clone(self) -> "NbtTag":
+        """同じ値を持つ新しいタグを作る。"""
         return type(self)(list(self._value))
 
     def __eq__(self, other) -> bool:
@@ -355,6 +359,7 @@ def clear(self) -> None:
         self._items.clear()
 
     def clone(self) -> "NbtTag":
+        """同じ値を持つ新しいタグを作る。"""
         copy = NbtList(self._element_type)
 
         # 要素も深くコピーする
@@ -471,6 +476,7 @@ def items(self) -> Iterator[Tuple[str, NbtTag]]:
         return iter(self._entries.items())
 
     def clone(self) -> "NbtTag":
+        """同じ値を持つ新しいタグを作る。"""
         copy = NbtCompound()
 
         # 挿入順のまま深くコピーする