Author:
Committer:
Parent: 9cda586ebd402df2e0543444329cfc1dd08172ea (Fix scala mods crashing with the json annotation cache.)
Branch:
Follows:
Precedes:

    Local uncommitted changes, not checked in to index

 src/main/java/net/minecraftforge/common/capabilities/ICapabilityProvider.java
index 2cc2d6bac..21ba77f9c 100644
@@ -28,30 +28,34 @@ 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
+     * The return value of this MIGHT change during runtime if this object gains or loses support
      * for a capability.
      *
      * Example:
-     *   A Pipe getting a cover placed on one side causing it loose the Inventory attachment function for that side.
+     *   A Pipe getting a cover placed on one side causing it lose the Inventory attachment function for that side.
      *
      * This is a light weight version of getCapability, intended for metadata uses.
      *
      * @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. As well, if this is false, it must 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 MUST be null if the object does not support the capability (as per {@link #hasCapability(Capability, EnumFacing)}).</il>
+     * <li>The return value CAN be the same for multiple faces.</li>
+     * </ul>
      *
      * @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.
+     * @return The requested capability. Returns null <em>exactly</em> when {@link #hasCapability(Capability, EnumFacing)} would return
+     * false, and never null otherwise.
      */
     @Nullable
     <T> T getCapability(@Nonnull Capability<T> capability, @Nullable EnumFacing facing);