Improve PHPDocs in world package

src/world/World.php

@@ -1562,6 +1562,7 @@ class World implements ChunkManager{
 	 * Larger AABBs (>= 2 blocks on any axis) are not accounted for.
 	 *
 	 * @return AxisAlignedBB[]
+	 * @phpstan-return list<AxisAlignedBB>
 	 */
 	private function getBlockCollisionBoxesForCell(int $x, int $y, int $z) : array{
 		$block = $this->getBlockAt($x, $y, $z);
@@ -2040,7 +2041,6 @@ class World implements ChunkManager{
 	 * @phpstan-return list<ExperienceOrb>
 	 */
 	public function dropExperience(Vector3 $pos, int $amount) : array{
-		/** @var ExperienceOrb[] $orbs */
 		$orbs = [];
 
 		foreach(ExperienceOrb::splitIntoOrbSizes($amount) as $split){
@@ -3083,6 +3083,7 @@ class World implements ChunkManager{
 	 * @phpstan-return Promise<Position>
 	 */
 	public function requestSafeSpawn(?Vector3 $spawn = null) : Promise{
+		/** @phpstan-var PromiseResolver<Position> $resolver */
 		$resolver = new PromiseResolver();
 		$spawn ??= $this->getSpawnLocation();
 		/*
@@ -3254,6 +3255,7 @@ class World implements ChunkManager{
 	private function enqueuePopulationRequest(int $chunkX, int $chunkZ, ?ChunkLoader $associatedChunkLoader) : Promise{
 		$chunkHash = World::chunkHash($chunkX, $chunkZ);
 		$this->addChunkHashToPopulationRequestQueue($chunkHash);
+		/** @phpstan-var PromiseResolver<Chunk> $resolver */
 		$resolver = $this->chunkPopulationRequestMap[$chunkHash] = new PromiseResolver();
 		if($associatedChunkLoader === null){
 			$temporaryLoader = new class implements ChunkLoader{};

src/world/format/Chunk.php

@@ -57,7 +57,10 @@ class Chunk{
 	 */
 	protected \SplFixedArray $subChunks;
 
-	/** @var Tile[] */
+	/**
+	 * @var Tile[]
+	 * @phpstan-var array<int, Tile>
+	 */
 	protected array $tiles = [];
 
 	protected HeightArray $heightMap;
@@ -210,6 +213,7 @@ class Chunk{
 
 	/**
 	 * @return Tile[]
+	 * @phpstan-return array<int, Tile>
 	 */
 	public function getTiles() : array{
 		return $this->tiles;
@@ -237,6 +241,7 @@ class Chunk{
 
 	/**
 	 * @return int[]
+	 * @phpstan-return non-empty-list<int>
 	 */
 	public function getHeightMapArray() : array{
 		return $this->heightMap->getValues();
@@ -244,6 +249,7 @@ class Chunk{
 
 	/**
 	 * @param int[] $values
+	 * @phpstan-param non-empty-list<int> $values
 	 */
 	public function setHeightMapArray(array $values) : void{
 		$this->heightMap = new HeightArray($values);

src/world/format/HeightArray.php

@@ -36,7 +36,7 @@ final class HeightArray{
 
 	/**
 	 * @param int[] $values ZZZZXXXX key bit order
-	 * @phpstan-param list<int> $values
+	 * @phpstan-param non-empty-list<int> $values
 	 */
 	public function __construct(array $values){
 		if(count($values) !== 256){
@@ -66,7 +66,7 @@ final class HeightArray{
 
 	/**
 	 * @return int[] ZZZZXXXX key bit order
-	 * @phpstan-return list<int>
+	 * @phpstan-return non-empty-list<int>
 	 */
 	public function getValues() : array{
 		return $this->array->toArray();

src/world/format/io/FastChunkSerializer.php

@@ -112,7 +112,6 @@ final class FastChunkSerializer{
 			$y = Binary::signByte($stream->getByte());
 			$airBlockId = $stream->getInt();
 
-			/** @var PalettedBlockArray[] $layers */
 			$layers = [];
 			for($i = 0, $layerCount = $stream->getByte(); $i < $layerCount; ++$i){
 				$layers[] = self::deserializePalettedArray($stream);

src/world/format/io/region/RegionWorldProvider.php

@@ -93,10 +93,12 @@ abstract class RegionWorldProvider extends BaseWorldProvider{
 	}
 
 	/**
-	 * @param int $regionX reference parameter
+	 * @param int|null $regionX reference parameter
-	 * @param int $regionZ reference parameter
+	 * @param int|null $regionZ reference parameter
 	 * @phpstan-param-out int $regionX
 	 * @phpstan-param-out int $regionZ
+	 *
+	 * TODO: make this private
 	 */
 	public static function getRegionIndex(int $chunkX, int $chunkZ, &$regionX, &$regionZ) : void{
 		$regionX = $chunkX >> 5;
@@ -154,6 +156,8 @@ abstract class RegionWorldProvider extends BaseWorldProvider{
 
 	/**
 	 * @return CompoundTag[]
+	 * @phpstan-return list<CompoundTag>
+	 *
 	 * @throws CorruptedChunkException
 	 */
 	protected static function getCompoundList(string $context, ListTag $list) : array{

src/world/light/LightPopulationTask.php

@@ -44,7 +44,7 @@ class LightPopulationTask extends AsyncTask{
 	private string $resultBlockLightArrays;
 
 	/**
-	 * @phpstan-param \Closure(array<int, LightArray> $blockLight, array<int, LightArray> $skyLight, array<int, int> $heightMap) : void $onCompletion
+	 * @phpstan-param \Closure(array<int, LightArray> $blockLight, array<int, LightArray> $skyLight, non-empty-list<int> $heightMap) : void $onCompletion
 	 */
 	public function __construct(Chunk $chunk, \Closure $onCompletion){
 		$this->chunk = FastChunkSerializer::serializeTerrain($chunk);
@@ -80,7 +80,10 @@ class LightPopulationTask extends AsyncTask{
 	}
 
 	public function onCompletion() : void{
-		/** @var int[] $heightMapArray */
+		/**
+		 * @var int[] $heightMapArray
+		 * @phpstan-var non-empty-list<int> $heightMapArray
+		 */
 		$heightMapArray = igbinary_unserialize($this->resultHeightMap);
 
 		/** @var LightArray[] $skyLightArrays */
@@ -90,7 +93,7 @@ class LightPopulationTask extends AsyncTask{
 
 		/**
 		 * @var \Closure
-		 * @phpstan-var \Closure(array<int, LightArray> $blockLight, array<int, LightArray> $skyLight, array<int, int> $heightMap) : void
+		 * @phpstan-var \Closure(array<int, LightArray> $blockLight, array<int, LightArray> $skyLight, non-empty-list<int> $heightMap) : void
 		 */
 		$callback = $this->fetchLocal(self::TLS_KEY_COMPLETION_CALLBACK);
 		$callback($blockLightArrays, $skyLightArrays, $heightMapArray);