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; package net.minecraftforge.common.capabilities;
import java.util.Map;
import javax.annotation.Nonnull; import javax.annotation.Nonnull;
import javax.annotation.Nullable; 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. * 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. * for a capability. It is not required to call this function before calling
* * {@link #getCapability(Capability, EnumFacing)}.
* Example: * <p>
* A Pipe getting a cover placed on one side causing it loose the Inventory attachment function for that side. * 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. * This is a light weight version of getCapability, intended for metadata uses.
* * </p>
* @param capability The capability to check * @param capability The capability to check
* @param facing The Side to check from: * @param facing The Side to check from:
* CAN BE NULL. Null is defined to represent 'internal' or 'self' * 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); boolean hasCapability(@Nonnull Capability<?> capability, @Nullable EnumFacing facing);
/** /**
* Retrieves the handler for the capability requested on the specific side. * 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. * <ul>
* The return value CAN be the same for multiple faces. * <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 capability The capability to check
* @param facing The Side to check from: * @param facing The Side to check from,
* CAN BE NULL. Null is defined to represent 'internal' or 'self' * <strong>CAN BE NULL</strong>. 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. Must <strong>NOT</strong> be null when {@link #hasCapability(Capability, EnumFacing)}
* would return true.
*/ */
@Nullable @Nullable
<T> T getCapability(@Nonnull Capability<T> capability, @Nullable EnumFacing facing); <T> T getCapability(@Nonnull Capability<T> capability, @Nullable EnumFacing facing);