Update JavaDoc

Author: ramidzkh

patchwork-capabilities/src/main/java/com/patchworkmc/mixin/capability/EntityMixin.java

@@ -55,10 +55,10 @@ private void initializeCapabilities(CallbackInfo callbackInfo) {
 
 	@Inject(method = "toTag", at = @At(value = "INVOKE", target = "Lnet/minecraft/entity/Entity;writeCustomDataToTag(Lnet/minecraft/nbt/CompoundTag;)V"))
 	private void serializeCapabilities(CompoundTag tag, CallbackInfoReturnable<CompoundTag> callbackInfoReturnable) {
-		CompoundTag compoundTag = serializeCaps();
+		CompoundTag capabilities = serializeCaps();
 
-		if (compoundTag != null) {
-			tag.put("ForgeCaps", compoundTag);
+		if (capabilities != null) {
+			tag.put("ForgeCaps", capabilities);
 		}
 	}
 

patchwork-capabilities/src/main/java/net/minecraftforge/common/capabilities/Capability.java

@@ -91,7 +91,7 @@ public interface IStorage<T> {
 		 * @param capability The capability being stored.
 		 * @param instance   An instance of that capability's interface.
 		 * @param side       The side of the object the instance is associated with.
-		 * @param nbt        A tag holding the data. Must not be null, as doesn't make sense to call this function with nothing to read...
+		 * @param nbt        A {@link Tag} holding the data. Must not be null, as doesn't make sense to call this function with nothing to read...
 		 */
 		void readNBT(Capability<T> capability, T instance, Direction side, Tag nbt);
 	}

patchwork-capabilities/src/main/java/net/minecraftforge/common/capabilities/CapabilityDispatcher.java

@@ -39,7 +39,8 @@
 /**
  * A high-speed implementation of a {@link Capability} delegator.
  * This is used to wrap the results of the {@link net.minecraftforge.event.AttachCapabilitiesEvent}.
- * It is HIGHLY recommended that you DO NOT use this approach unless
+ *
+ * <p>It is HIGHLY recommended that you DO NOT use this approach unless
  * you MUST delegate to multiple providers instead just implementing
  * your handlers using normal if statements.
  *
@@ -59,34 +60,34 @@ public CapabilityDispatcher(Map<Identifier, ICapabilityProvider> providers, List
 
 	@SuppressWarnings("unchecked")
 	public CapabilityDispatcher(Map<Identifier, ICapabilityProvider> providers, List<Runnable> listeners, @Nullable ICapabilityProvider parent) {
-		List<ICapabilityProvider> lstCaps = Lists.newArrayList();
-		List<INBTSerializable<Tag>> lstWriters = Lists.newArrayList();
-		List<String> lstNames = Lists.newArrayList();
-		this.listeners = listeners;
+		List<ICapabilityProvider> capabilities = Lists.newArrayList();
+		List<INBTSerializable<Tag>> writers = Lists.newArrayList();
+		List<String> names = Lists.newArrayList();
 
 		// Parents go first!
 		if (parent != null) {
-			lstCaps.add(parent);
+			capabilities.add(parent);
 
 			if (parent instanceof INBTSerializable) {
-				lstWriters.add((INBTSerializable<Tag>) parent);
-				lstNames.add("Parent");
+				writers.add((INBTSerializable<Tag>) parent);
+				names.add("Parent");
 			}
 		}
 
 		for (Map.Entry<Identifier, ICapabilityProvider> entry : providers.entrySet()) {
 			ICapabilityProvider prov = entry.getValue();
-			lstCaps.add(prov);
+			capabilities.add(prov);
 
 			if (prov instanceof INBTSerializable) {
-				lstWriters.add((INBTSerializable<Tag>) prov);
-				lstNames.add(entry.getKey().toString());
+				writers.add((INBTSerializable<Tag>) prov);
+				names.add(entry.getKey().toString());
 			}
 		}
 
-		this.providers = lstCaps.toArray(new ICapabilityProvider[0]);
-		writers = lstWriters.toArray(new INBTSerializable[0]);
-		names = lstNames.toArray(new String[0]);
+		this.listeners = listeners;
+		this.providers = capabilities.toArray(new ICapabilityProvider[0]);
+		this.writers = writers.toArray(new INBTSerializable[0]);
+		this.names = names.toArray(new String[0]);
 	}
 
 	@Nonnull
@@ -144,8 +145,9 @@ public void deserializeNBT(CompoundTag tag) {
 	// Called from ItemStack to compare equality.
 	// Only compares serializable caps.
 	public boolean areCompatible(@Nullable CapabilityDispatcher other) {
+		// Do some checks before costly NBT serialization and comparisons
 		if (other == null) {
-			return this.writers.length == 0;  // Done this way so we can do some pre-checks before doing the costly NBT serialization and compare
+			return this.writers.length == 0;
 		}
 
 		if (this.writers.length == 0) {

patchwork-capabilities/src/main/java/net/minecraftforge/common/capabilities/CapabilityInject.java

@@ -25,8 +25,8 @@
 import java.lang.annotation.Target;
 
 /**
- * When placed on a FIELD, the field will be set to an
- * instance of Capability once that capability is registered.
+ * When placed on a field, the field will be set to an
+ * instance of {@link Capability} once that capability is registered.
  * That field must be static and be able to hold a instance
  * of 'Capability'
  *
@@ -36,7 +36,7 @@
  * private static final Capability<IExampleCapability> TEST_CAP = null;
  * </blockquote>
  *
- * <p>When placed on a METHOD, the method will be invoked once the
+ * <p>When placed on a method, the method will be invoked once the
  * capability is registered. This allows you to have a 'enable features'
  * callback. It MUST have one parameter of type 'Capability;
  *
@@ -46,7 +46,7 @@
  * private static void capRegistered(Capability&lt;IExampleCapability&gt; cap) {}
  * </blockquote>
  *
- * <b>Warning</b>: Capability injections are run in the thread that the capablity is registered.
+ * <b>Warning</b>: Capability injections are run in the thread that the capability is registered.
  * Due to parallel mod loading, this can potentially be off of the main thread.
  */
 @Retention(RetentionPolicy.RUNTIME)

patchwork-capabilities/src/main/java/net/minecraftforge/common/capabilities/CapabilityManager.java

@@ -40,7 +40,7 @@ public enum CapabilityManager {
 	private final Map<String, Capability<?>> providers = new HashMap<>();
 
 	/**
-	 * Registers a capability to be consumed by others.
+	 * Registers a {@link Capability} to be consumed by others.
 	 * APIs who define the capability should call this.
 	 * To retrieve the Capability instance, use the @CapabilityInject annotation.
 	 * This method is safe to call during parallel mod loading.

patchwork-capabilities/src/main/java/net/minecraftforge/common/capabilities/ICapabilityProvider.java

@@ -30,7 +30,8 @@ public interface ICapabilityProvider {
 	/**
 	 * Retrieves the {@link LazyOptional optional} handler for the capability requested on the specific side.
 	 * The return value <strong>CAN</strong> be the same for multiple faces.
-	 * Modders are encouraged to cache this value, using the listener capabilities of the optional to
+	 *
+	 * <p>Modders are encouraged to cache this value, using the listener capabilities of the optional to
 	 * be notified if the requested capability get lost.
 	 *
 	 * @param capability The {@link Capability capability} to check

patchwork-capabilities/src/main/java/net/minecraftforge/common/util/INBTSerializable.java

@@ -23,7 +23,7 @@
 
 /**
  * An interface designed to unify various things in the Minecraft
- * code base that can be serialized to and from a NBT tag.
+ * code base that can be serialized to and from an {@link Tag NBT tag}
  */
 public interface INBTSerializable<T extends Tag> {
 	T serializeNBT();

patchwork-capabilities/src/main/java/net/minecraftforge/event/AttachCapabilitiesEvent.java

@@ -31,16 +31,16 @@
 import net.minecraft.util.Identifier;
 
 /**
- * Fired whenever an object with Capabilities support (currently {@link net.minecraft.block.entity.BlockEntity block entities}, {@link net.minecraft.item.Item items}, and {@link javax.swing.text.html.parser.Entity entities})
+ * Fired whenever an object with Capabilities support (currently {@link net.minecraft.block.entity.BlockEntity block entities}, {@link net.minecraft.item.ItemStack items}, {@link net.minecraft.entity.Entity entities}, {@link net.minecraft.world.World worlds} and {@link net.minecraft.world.chunk.WorldChunk chunks})
  * is created. Allowing for the attachment of arbitrary capability providers.
  *
  * <p>Please note that as this is fired for ALL object creations efficient code is recommended.
  * And if possible use one of the sub-classes to filter your intended objects.
  */
 public class AttachCapabilitiesEvent<T> extends GenericEvent<T> {
-	private final T obj;
-	private final Map<Identifier, ICapabilityProvider> caps = Maps.newLinkedHashMap();
-	private final Map<Identifier, ICapabilityProvider> view = Collections.unmodifiableMap(caps);
+	private final T object;
+	private final Map<Identifier, ICapabilityProvider> capabilities = Maps.newLinkedHashMap();
+	private final Map<Identifier, ICapabilityProvider> view = Collections.unmodifiableMap(capabilities);
 	private final List<Runnable> listeners = Lists.newArrayList();
 	private final List<Runnable> listenersView = Collections.unmodifiableList(listeners);
 
@@ -49,32 +49,33 @@ public AttachCapabilitiesEvent() {
 		this(null, null);
 	}
 
-	public AttachCapabilitiesEvent(Class<T> type, T obj) {
+	public AttachCapabilitiesEvent(Class<T> type, T object) {
 		super(type);
-		this.obj = obj;
+		this.object = object;
 	}
 
 	/**
-	 * Retrieves the object that is being created, Not much state is set.
+	 * Retrieves the object that is being created.<br>
+	 * <b>Note:</b> Object creation is still incomplete at this point
 	 */
 	public T getObject() {
-		return this.obj;
+		return this.object;
 	}
 
 	/**
-	 * Adds a capability to be attached to this object.
+	 * Adds a {@link net.minecraftforge.common.capabilities.Capability} to be attached to this object.
 	 * Keys MUST be unique, it is suggested that you set the domain to your mod ID.
-	 * If the capability is an instance of INBTSerializable, this key will be used when serializing this capability.
+	 * If the capability is an instance of {@link net.minecraftforge.common.util.INBTSerializable}, this key will be used when serializing this capability.
 	 *
 	 * @param key The name of owner of this capability provider.
-	 * @param cap The capability provider
+	 * @param cap The {@link ICapabilityProvider capability provider}
 	 */
 	public void addCapability(Identifier key, ICapabilityProvider cap) {
-		if (caps.containsKey(key)) {
+		if (capabilities.containsKey(key)) {
 			throw new IllegalStateException("Duplicate Capability Key: " + key + " " + cap);
 		}
 
-		this.caps.put(key, cap);
+		this.capabilities.put(key, cap);
 	}
 
 	/**