Update documentation on FinalizeSpawn (#9467)

src/main/java/net/minecraftforge/event/ForgeEventFactory.java

@@ -193,12 +193,34 @@ public class ForgeEventFactory
      * Vanilla calls to {@link Mob#finalizeSpawn} are replaced with calls to this method via coremod.<br>
      * Mods should call this method in place of calling {@link Mob#finalizeSpawn}. Super calls (from within overrides) should not be wrapped.
      * <p>
-     * Returns the SpawnGroupData from this event, or null if it was canceled.
+     * When interfacing with this event, write all code as normal, and replace the call to {@link Mob#finalizeSpawn} with a call to this method.<p>
+     * As an example, the following code block:
+     * <code><pre>
+     * var zombie = new Zombie(level);
+     * zombie.finalizeSpawn(level, difficulty, spawnType, spawnData, spawnTag);
+     * level.tryAddFreshEntityWithPassengers(zombie);
+     * if (zombie.isAddedToWorld()) {
+     *     // Do stuff with your new zombie
+     * }
+     * </pre></code>
+     * Would become:
+     * <code><pre>
+     * var zombie = new Zombie(level);
+     * ForgeEventFactory.onFinalizeSpawn(zombie, level, difficulty, spawnType, spawnData, spawnTag);
+     * level.tryAddFreshEntityWithPassengers(zombie);
+     * if (zombie.isAddedToWorld()) {
+     *     // Do stuff with your new zombie
+     * }
+     * </pre></code>
+     * The only code that changes is the {@link Mob#finalizeSpawn} call.
+     * @return The SpawnGroupData from this event, or null if it was canceled. The return value of this method has no bearing on if the entity will be spawned.
      * @see MobSpawnEvent.FinalizeSpawn
      * @see Mob#finalizeSpawn(ServerLevelAccessor, DifficultyInstance, MobSpawnType, SpawnGroupData, CompoundTag)
+     * @apiNote Callers do not need to check if the entity's spawn was cancelled, as the spawn will be blocked by Forge.
      * @implNote Changes to the signature of this method must be reflected in the method redirector coremod. 
      */
     @Nullable
+    @SuppressWarnings("deprecation") // Call to deprecated Mob#finalizeSpawn is expected.
     public static SpawnGroupData onFinalizeSpawn(Mob mob, ServerLevelAccessor level, DifficultyInstance difficulty, MobSpawnType spawnType, @Nullable SpawnGroupData spawnData, @Nullable CompoundTag spawnTag)
     {
         var event = new MobSpawnEvent.FinalizeSpawn(mob, level, mob.getX(), mob.getY(), mob.getZ(), difficulty, spawnType, spawnData, spawnTag, null);

src/main/java/net/minecraftforge/event/entity/living/MobSpawnEvent.java

@@ -86,14 +86,16 @@ public abstract class MobSpawnEvent extends EntityEvent
     }
 
     /**
-     * This event is fired before {@link Mob#finalizeSpawn(ServerLevelAccessor, DifficultyInstance, MobSpawnType, SpawnGroupData, CompoundTag)} is called.<br>
+     * This event is fired before {@link Mob#finalizeSpawn} is called.<br>
      * This allows mods to control mob initialization.<br>
-     * In vanilla code, this event is injected by a transformer and not via patch, so calls cannot be traced via call hierarchy.
+     * In vanilla code, this event is injected by a transformer and not via patch, so calls cannot be traced via call hierarchy (it is not source-visible).
      * <p>
      * Canceling this event will result in {@link Mob#finalizeSpawn} not being called, and the returned value always being null, instead of propagating the SpawnGroupData.<br>
-     * The entity will still be spawned. If you want to prevent the spawn, use {@link FinalizeSpawn#cancelSpawn()}
+     * The entity will still be spawned. If you want to prevent the spawn, use {@link FinalizeSpawn#setSpawnCancelled}, which will cause Forge to prevent the spawn.
      * <p>
      * This event is fired on {@link MinecraftForge#EVENT_BUS}, and is only fired on the logical server.
+     * @see ForgeEventFactory#onFinalizeSpawn
+     * @apiNote Callers do not need to check if the entity's spawn was cancelled, as the spawn will be blocked by Forge.
      */
     @Cancelable
     public static class FinalizeSpawn extends MobSpawnEvent