From 97d58aeaa1ca0ee8b70cb9f1491edcadc5635aae Mon Sep 17 00:00:00 2001
From: tterrag <tterrag1098@gmail.com>
Date: Sat, 14 Jul 2018 17:08:22 -0400
Subject: [PATCH] Clean up and improve ICapabilityProvider javadocs (#4978)

---
 .../capabilities/ICapabilityProvider.java     | 37 ++++++++++++-------
 1 file changed, 24 insertions(+), 13 deletions(-)

diff --git a/src/main/java/net/minecraftforge/common/capabilities/ICapabilityProvider.java b/src/main/java/net/minecraftforge/common/capabilities/ICapabilityProvider.java
index fcb4bb4c6..5bf8a3fa4 100644
--- a/src/main/java/net/minecraftforge/common/capabilities/ICapabilityProvider.java
+++ b/src/main/java/net/minecraftforge/common/capabilities/ICapabilityProvider.java
@@ -19,6 +19,8 @@
 
 package net.minecraftforge.common.capabilities;
 
+import java.util.Map;
+
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 
@@ -28,30 +30,39 @@ public interface ICapabilityProvider
 {
     /**
      * Determines if this object has support for the capability in question on the specific side.
-     * The return value of this MIGHT change during runtime if this object gains or looses support
-     * for a capability.
-     *
-     * Example:
-     *   A Pipe getting a cover placed on one side causing it loose the Inventory attachment function for that side.
-     *
+     * The return value of this MIGHT change during runtime if this object gains or loses support
+     * for a capability. It is not required to call this function before calling 
+     * {@link #getCapability(Capability, EnumFacing)}.
+     * <p>
+     * Basically, this method functions analogously to {@link Map#containsKey(Object)}.
+     * <p>
+     * <em>Example:</em>
+     *   A Pipe getting a cover placed on one side causing it lose the Inventory attachment function for that side.
+     * </p><p>
      * This is a light weight version of getCapability, intended for metadata uses.
-     *
+     * </p>
      * @param capability The capability to check
      * @param facing The Side to check from:
      *   CAN BE NULL. Null is defined to represent 'internal' or 'self'
-     * @return True if this object supports the capability.
+     * @return True if this object supports the capability. If true, then {@link #getCapability(Capability, EnumFacing)} 
+     * must not return null.
      */
     boolean hasCapability(@Nonnull Capability<?> capability, @Nullable EnumFacing facing);
 
     /**
      * Retrieves the handler for the capability requested on the specific side.
-     * The return value CAN be null if the object does not support the capability.
-     * The return value CAN be the same for multiple faces.
+     * <ul>
+     * <li>The return value <strong>CAN</strong> be null if the object does not support the capability.</il>
+     * <li>The return value <strong>CAN</strong> be the same for multiple faces.</li>
+     * </ul>
+     * <p>
+     * Basically, this method functions analogously to {@link Map#get(Object)}.
      *
      * @param capability The capability to check
-     * @param facing The Side to check from:
-     *   CAN BE NULL. Null is defined to represent 'internal' or 'self'
-     * @return The requested capability. Returns null when {@link #hasCapability(Capability, EnumFacing)} would return false.
+     * @param facing The Side to check from, 
+     *   <strong>CAN BE NULL</strong>. Null is defined to represent 'internal' or 'self'
+     * @return The requested capability. Must <strong>NOT</strong> be null when {@link #hasCapability(Capability, EnumFacing)} 
+     * would return true. 
      */
     @Nullable
     <T> T getCapability(@Nonnull Capability<T> capability, @Nullable EnumFacing facing);