keith/ForgePatch
1
0
Fork 0
Code Issues Pull requests Projects Releases 2 Wiki Activity

Clean up and improve ICapabilityProvider javadocs (#4978)

Browse source
This commit is contained in:
tterrag 2018-07-14 17:08:22 -04:00 committed by LexManos
parent c6f001bb6c
commit 97d58aeaa1
1 changed files with 24 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

37
src/main/java/net/minecraftforge/common/capabilities/ICapabilityProvider.java
View file

@ -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);