Add @nullable and friends (FabricMC#1007)

* Boost to Loom 0.5
Add null related annotations

* Rearrange nullable to be overline

* Fix anno sorting for picky

* Add imports

* Address feedback

* Fix import

fabric-events-interaction-v0/src/main/java/net/fabricmc/fabric/api/block/BlockPickInteractionAware.java

@@ -16,6 +16,8 @@
 
 package net.fabricmc.fabric.api.block;
 
+import org.jetbrains.annotations.Nullable;
+
 import net.minecraft.block.BlockState;
 import net.minecraft.entity.player.PlayerEntity;
 import net.minecraft.item.ItemStack;
@@ -24,5 +26,5 @@
 import net.minecraft.world.BlockView;
 
 public interface BlockPickInteractionAware {
-	ItemStack getPickedStack(BlockState state, BlockView view, BlockPos pos, /* nullable */ PlayerEntity player, /* nullable */ HitResult result);
+	ItemStack getPickedStack(BlockState state, BlockView view, BlockPos pos, @Nullable PlayerEntity player, @Nullable HitResult result);
 }

fabric-events-interaction-v0/src/main/java/net/fabricmc/fabric/api/entity/EntityPickInteractionAware.java

@@ -16,10 +16,12 @@
 
 package net.fabricmc.fabric.api.entity;
 
+import org.jetbrains.annotations.Nullable;
+
 import net.minecraft.entity.player.PlayerEntity;
 import net.minecraft.item.ItemStack;
 import net.minecraft.util.hit.HitResult;
 
 public interface EntityPickInteractionAware {
-	ItemStack getPickedStack(/* nullable */ PlayerEntity player, /* nullable */ HitResult result);
+	ItemStack getPickedStack(@Nullable PlayerEntity player, @Nullable HitResult result);
 }

fabric-events-interaction-v0/src/main/java/net/fabricmc/fabric/api/event/player/AttackEntityCallback.java

@@ -16,6 +16,8 @@
 
 package net.fabricmc.fabric.api.event.player;
 
+import org.jetbrains.annotations.Nullable;
+
 import net.minecraft.entity.Entity;
 import net.minecraft.entity.player.PlayerEntity;
 import net.minecraft.util.ActionResult;
@@ -50,5 +52,5 @@ public interface AttackEntityCallback {
 			}
 	);
 
-	ActionResult interact(PlayerEntity player, World world, Hand hand, Entity entity, /* Nullable */ EntityHitResult hitResult);
+	ActionResult interact(PlayerEntity player, World world, Hand hand, Entity entity, @Nullable EntityHitResult hitResult);
 }

fabric-events-interaction-v0/src/main/java/net/fabricmc/fabric/api/event/player/UseEntityCallback.java

@@ -16,6 +16,8 @@
 
 package net.fabricmc.fabric.api.event.player;
 
+import org.jetbrains.annotations.Nullable;
+
 import net.minecraft.entity.Entity;
 import net.minecraft.entity.player.PlayerEntity;
 import net.minecraft.util.ActionResult;
@@ -50,5 +52,5 @@ public interface UseEntityCallback {
 			}
 	);
 
-	ActionResult interact(PlayerEntity player, World world, Hand hand, Entity entity, /* Nullable */ EntityHitResult hitResult);
+	ActionResult interact(PlayerEntity player, World world, Hand hand, Entity entity, @Nullable EntityHitResult hitResult);
 }

fabric-game-rule-api-v1/src/main/java/net/fabricmc/fabric/api/gamerule/v1/GameRuleFactory.java

@@ -22,6 +22,7 @@
 
 import com.mojang.brigadier.arguments.DoubleArgumentType;
 import com.mojang.brigadier.arguments.IntegerArgumentType;
+import org.jetbrains.annotations.Nullable;
 
 import net.minecraft.server.MinecraftServer;
 import net.minecraft.world.GameRules;
@@ -140,7 +141,7 @@ public static GameRules.Type<GameRules.IntRule> createIntRule(int defaultValue,
 	 * @param changedCallback a callback that is invoked when the value of a game rule has changed
 	 * @return an integer rule type
 	 */
-	public static GameRules.Type<GameRules.IntRule> createIntRule(int defaultValue, int minimumValue, int maximumValue, /* @Nullable */ BiConsumer<MinecraftServer, GameRules.IntRule> changedCallback) {
+	public static GameRules.Type<GameRules.IntRule> createIntRule(int defaultValue, int minimumValue, int maximumValue, @Nullable BiConsumer<MinecraftServer, GameRules.IntRule> changedCallback) {
 		return new GameRules.Type<>(
 				() -> IntegerArgumentType.integer(minimumValue, maximumValue),
 				type -> new BoundedIntRule(type, defaultValue, minimumValue, maximumValue), // Internally use a bounded int rule

fabric-game-rule-api-v1/src/main/java/net/fabricmc/fabric/api/gamerule/v1/rule/EnumRule.java

@@ -26,6 +26,7 @@
 import com.mojang.brigadier.context.CommandContext;
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
+import org.jetbrains.annotations.Nullable;
 
 import net.minecraft.server.MinecraftServer;
 import net.minecraft.server.command.ServerCommandSource;
@@ -144,7 +145,7 @@ public boolean supports(E value) {
 		return this.supportedValues.contains(value);
 	}
 
-	public void set(E value, /* @Nullable */ MinecraftServer server) throws IllegalArgumentException {
+	public void set(E value, @Nullable MinecraftServer server) throws IllegalArgumentException {
 		checkNotNull(value);
 
 		if (!this.supports(value)) {

fabric-game-rule-api-v1/src/main/java/net/fabricmc/fabric/impl/gamerule/RuleKeyExtensions.java

@@ -16,10 +16,12 @@
 
 package net.fabricmc.fabric.impl.gamerule;
 
+import org.jetbrains.annotations.Nullable;
+
 import net.fabricmc.fabric.api.gamerule.v1.CustomGameRuleCategory;
 
 public interface RuleKeyExtensions {
-	/* @Nullable */
+	@Nullable
 	CustomGameRuleCategory fabric_getCustomCategory();
 
 	void fabric_setCustomCategory(CustomGameRuleCategory customCategory);

fabric-game-rule-api-v1/src/main/java/net/fabricmc/fabric/mixin/gamerule/RuleKeyMixin.java

@@ -16,6 +16,7 @@
 
 package net.fabricmc.fabric.mixin.gamerule;
 
+import org.jetbrains.annotations.Nullable;
 import org.spongepowered.asm.mixin.Mixin;
 import org.spongepowered.asm.mixin.Unique;
 
@@ -26,8 +27,8 @@
 
 @Mixin(GameRules.Key.class)
 public abstract class RuleKeyMixin implements RuleKeyExtensions {
-	/* @Nullable */
 	@Unique
+	@Nullable
 	private CustomGameRuleCategory customCategory;
 
 	@Override

fabric-models-v0/src/main/java/net/fabricmc/fabric/api/client/model/ModelResourceProvider.java

@@ -16,6 +16,8 @@
 
 package net.fabricmc.fabric.api.client.model;
 
+import org.jetbrains.annotations.Nullable;
+
 import net.minecraft.client.render.model.UnbakedModel;
 import net.minecraft.util.Identifier;
 
@@ -46,5 +48,6 @@ public interface ModelResourceProvider {
 	 * @return The loaded UnbakedModel, or null if this ModelResourceProvider doesn't handle a specific Identifier
 	 * (or if there was no error!).
 	 */
-	/* @Nullable */ UnbakedModel loadModelResource(Identifier resourceId, ModelProviderContext context) throws ModelProviderException;
+	@Nullable
+	UnbakedModel loadModelResource(Identifier resourceId, ModelProviderContext context) throws ModelProviderException;
 }

fabric-models-v0/src/main/java/net/fabricmc/fabric/api/client/model/ModelVariantProvider.java

@@ -16,6 +16,8 @@
 
 package net.fabricmc.fabric.api.client.model;
 
+import org.jetbrains.annotations.Nullable;
+
 import net.minecraft.client.render.model.UnbakedModel;
 import net.minecraft.client.util.ModelIdentifier;
 
@@ -43,5 +45,6 @@ public interface ModelVariantProvider {
 	 * @return The loaded UnbakedModel, or null if this ModelVariantProvider doesn't handle a specific Identifier
 	 * (or if there was no error!).
 	 */
-	/* @Nullable */ UnbakedModel loadModelVariant(ModelIdentifier modelId, ModelProviderContext context) throws ModelProviderException;
+	@Nullable
+	UnbakedModel loadModelVariant(ModelIdentifier modelId, ModelProviderContext context) throws ModelProviderException;
 }

fabric-models-v0/src/main/java/net/fabricmc/fabric/impl/client/model/ModelLoadingRegistryImpl.java

@@ -27,6 +27,7 @@
 import com.google.common.collect.Lists;
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
+import org.jetbrains.annotations.Nullable;
 
 import net.minecraft.client.render.model.ModelLoader;
 import net.minecraft.client.render.model.UnbakedModel;
@@ -139,12 +140,12 @@ private <T> UnbakedModel loadCustomModel(CustomModelItf<T> function, Collection<
 			}
 		}
 
-		/* @Nullable */
+		@Nullable
 		public UnbakedModel loadModelFromResource(Identifier resourceId) {
 			return loadCustomModel((r) -> r.loadModelResource(resourceId, this), modelResourceProviders, "resource provider");
 		}
 
-		/* @Nullable */
+		@Nullable
 		public UnbakedModel loadModelFromVariant(Identifier variantId) {
 			if (!(variantId instanceof ModelIdentifier)) {
 				return loadModelFromResource(variantId);

fabric-object-builder-api-v1/src/main/java/net/fabricmc/fabric/api/object/builder/v1/villager/VillagerProfessionBuilder.java

@@ -19,6 +19,7 @@
 import static com.google.common.base.Preconditions.checkState;
 
 import com.google.common.collect.ImmutableSet;
+import org.jetbrains.annotations.Nullable;
 
 import net.minecraft.block.Block;
 import net.minecraft.block.Blocks;
@@ -46,14 +47,15 @@ public final class VillagerProfessionBuilder {
 	private final ImmutableSet.Builder<Block> secondaryJobSiteBlockBuilder = ImmutableSet.builder();
 	private Identifier identifier;
 	private PointOfInterestType pointOfInterestType;
-	/* @Nullable */
+	@Nullable
 	private SoundEvent workSoundEvent;
 
 	private VillagerProfessionBuilder() {
 	}
 
 	/**
 	 * Creates a builder instance to allow for creation of a {@link VillagerProfession}.
+	 *
 	 * @return A new builder.
 	 */
 	public static VillagerProfessionBuilder create() {
@@ -140,7 +142,7 @@ public VillagerProfessionBuilder secondaryJobSites(Iterable<Block> blocks) {
 	 * @param workSoundEvent The {@link SoundEvent} to be played.
 	 * @return this builder.
 	 */
-	public VillagerProfessionBuilder workSound(/* @Nullable */ SoundEvent workSoundEvent) {
+	public VillagerProfessionBuilder workSound(@Nullable SoundEvent workSoundEvent) {
 		this.workSoundEvent = workSoundEvent;
 		return this;
 	}

fabric-object-builder-api-v1/src/main/java/net/fabricmc/fabric/impl/object/builder/FabricBlockInternals.java

@@ -19,6 +19,8 @@
 import java.util.ArrayList;
 import java.util.List;
 
+import org.jetbrains.annotations.Nullable;
+
 import net.minecraft.block.Block;
 import net.minecraft.item.Item;
 import net.minecraft.tag.Tag;
@@ -56,7 +58,8 @@ public static void onBuild(Block.Settings settings, Block block) {
 
 	public static final class ExtraData {
 		private final List<MiningLevel> miningLevels = new ArrayList<>();
-		/* @Nullable */ private Boolean breakByHand;
+		@Nullable
+		private Boolean breakByHand;
 
 		public ExtraData(Block.Settings settings) {
 		}

fabric-object-builder-api-v1/src/main/java/net/fabricmc/fabric/mixin/object/builder/VillagerProfessionAccessor.java

@@ -16,6 +16,7 @@
 
 package net.fabricmc.fabric.mixin.object.builder;
 
+import org.jetbrains.annotations.Nullable;
 import org.spongepowered.asm.mixin.Mixin;
 import org.spongepowered.asm.mixin.gen.Invoker;
 import com.google.common.collect.ImmutableSet;
@@ -29,7 +30,7 @@
 @Mixin(VillagerProfession.class)
 public interface VillagerProfessionAccessor {
 	@Invoker("<init>")
-	static VillagerProfession create(String id, PointOfInterestType type, ImmutableSet<Item> gatherableItems, ImmutableSet<Block> secondaryJobSites, /* @Nullable */ SoundEvent soundEvent) {
+	static VillagerProfession create(String id, PointOfInterestType type, ImmutableSet<Item> gatherableItems, ImmutableSet<Block> secondaryJobSites, @Nullable SoundEvent soundEvent) {
 		throw new AssertionError("Untransformed accessor!");
 	}
 }

fabric-registry-sync-v0/src/main/java/net/fabricmc/fabric/impl/registry/sync/RegistrySyncManager.java

@@ -35,6 +35,7 @@
 import it.unimi.dsi.fastutil.objects.Object2IntOpenHashMap;
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
+import org.jetbrains.annotations.Nullable;
 
 import net.minecraft.nbt.CompoundTag;
 import net.minecraft.network.Packet;
@@ -105,7 +106,8 @@ public static void receivePacket(PacketContext context, PacketByteBuf buf, boole
 	 * @param activeTag contains the registry ids that were previously read and applied, can be null.
 	 * @return a {@link CompoundTag} to save or sync, null when empty
 	 */
-	public static CompoundTag toTag(boolean isClientSync, CompoundTag activeTag) {
+	@Nullable
+	public static CompoundTag toTag(boolean isClientSync, @Nullable CompoundTag activeTag) {
 		CompoundTag mainTag = new CompoundTag();
 
 		for (Identifier registryId : Registry.REGISTRIES.getIds()) {

fabric-renderer-api-v1/src/main/java/net/fabricmc/fabric/api/renderer/v1/Renderer.java

@@ -16,6 +16,8 @@
 
 package net.fabricmc.fabric.api.renderer.v1;
 
+import org.jetbrains.annotations.Nullable;
+
 import net.minecraft.util.Identifier;
 
 import net.fabricmc.fabric.api.renderer.v1.material.MaterialFinder;
@@ -50,6 +52,7 @@ public interface Renderer {
 	 * Return a material previously registered via {@link #registerMaterial(Identifier, RenderMaterial)}.
 	 * Will return null if no material was found matching the given identifier.
 	 */
+	@Nullable
 	RenderMaterial materialById(Identifier id);
 
 	/**

fabric-renderer-api-v1/src/main/java/net/fabricmc/fabric/api/renderer/v1/RendererAccess.java

@@ -16,6 +16,8 @@
 
 package net.fabricmc.fabric.api.renderer.v1;
 
+import org.jetbrains.annotations.Nullable;
+
 import net.fabricmc.fabric.impl.renderer.RendererAccessImpl;
 
 /**
@@ -37,6 +39,7 @@ public interface RendererAccess {
 	 * Access to the current {@link Renderer} for creating and retrieving model builders
 	 * and materials. Will return null if no render plug in is active.
 	 */
+	@Nullable
 	Renderer getRenderer();
 
 	/**

fabric-renderer-api-v1/src/main/java/net/fabricmc/fabric/api/renderer/v1/mesh/MutableQuadView.java

@@ -16,6 +16,8 @@
 
 package net.fabricmc.fabric.api.renderer.v1.mesh;
 
+import org.jetbrains.annotations.Nullable;
+
 import net.minecraft.client.render.model.BakedQuad;
 import net.minecraft.client.texture.Sprite;
 import net.minecraft.client.util.math.Vector3f;
@@ -115,7 +117,8 @@ public interface MutableQuadView extends QuadView {
 	 * is computed based on face geometry and must be non-null in vanilla quads.
 	 * That computed value is returned by {@link #lightFace()}.
 	 */
-	MutableQuadView cullFace(Direction face);
+	@Nullable
+	MutableQuadView cullFace(@Nullable Direction face);
 
 	/**
 	 * Provides a hint to renderer about the facing of this quad. Not required,
@@ -130,6 +133,7 @@ public interface MutableQuadView extends QuadView {
 	 * <p>Note: This value is not persisted independently when the quad is encoded.
 	 * When reading encoded quads, this value will always be the same as {@link #lightFace()}.
 	 */
+	@Nullable
 	MutableQuadView nominalFace(Direction face);
 
 	/**

fabric-renderer-api-v1/src/main/java/net/fabricmc/fabric/api/renderer/v1/mesh/QuadView.java

@@ -16,6 +16,9 @@
 
 package net.fabricmc.fabric.api.renderer.v1.mesh;
 
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
 import net.minecraft.client.render.VertexFormats;
 import net.minecraft.client.render.model.BakedQuad;
 import net.minecraft.client.texture.Sprite;
@@ -77,6 +80,7 @@ public interface QuadView {
 	 * calculations and will be the block face to which the quad is most closely aligned. Always
 	 * the same as cull face for quads that are on a block face, but never null.
 	 */
+	@NotNull
 	Direction lightFace();
 
 	/**
@@ -85,7 +89,7 @@ public interface QuadView {
 	 *
 	 * @see MutableQuadView#cullFace(Direction)
 	 */
-	Direction cullFace();
+	@Nullable Direction cullFace();
 
 	/**
 	 * See {@link MutableQuadView#nominalFace(Direction)}.
@@ -135,7 +139,7 @@ default BakedQuad toBakedQuad(int spriteIndex, Sprite sprite, boolean isItem) {
 	 * Pass a non-null target to avoid allocation - will be returned with values.
 	 * Otherwise returns a new instance.
 	 */
-	Vector3f copyPos(int vertexIndex, Vector3f target);
+	Vector3f copyPos(int vertexIndex, @Nullable Vector3f target);
 
 	/**
 	 * Convenience: access x, y, z by index 0-2.
@@ -167,7 +171,8 @@ default BakedQuad toBakedQuad(int spriteIndex, Sprite sprite, boolean isItem) {
 	 * Pass a non-null target to avoid allocation - will be returned with values.
 	 * Otherwise returns a new instance. Returns null if normal not present.
 	 */
-	Vector3f copyNormal(int vertexIndex, Vector3f target);
+	@Nullable
+	Vector3f copyNormal(int vertexIndex, @Nullable Vector3f target);
 
 	/**
 	 * Will return {@link Float#NaN} if normal not present.

fabric-renderer-api-v1/src/main/java/net/fabricmc/fabric/api/renderer/v1/model/ModelHelper.java

@@ -20,6 +20,7 @@
 import java.util.List;
 
 import com.google.common.collect.ImmutableList;
+import org.jetbrains.annotations.Contract;
 
 import net.minecraft.client.MinecraftClient;
 import net.minecraft.client.render.model.BakedQuad;
@@ -56,6 +57,7 @@ public static int toFaceIndex(Direction face) {
 	 * optionally including the null face. (Use < or  <= {@link #NULL_FACE_ID}
 	 * to exclude or include the null value, respectively.)
 	 */
+	@Contract("null -> null")
 	public static Direction faceFromIndex(int faceIndex) {
 		return FACES[faceIndex];
 	}