Minor cleanup of pocket computer upgrades

- General improvements of the docs.
 - Move all ItemStack code to the ItemPocketComputer class
 - Make PocketAPI execute on the server thread, rather than the computer
   thread

src/main/java/dan200/computercraft/api/pocket/IPocketAccess.java

@@ -15,25 +15,25 @@ import java.util.Map;
 public interface IPocketAccess
 {
     /**
-     * Gets the holding entity of this item
+     * Gets the entity holding this item.
      *
-     * @return The holding entity, may be {@code null}.
+     * @return The holding entity. This may be {@code null}.
      */
     @Nullable
     Entity getEntity();
 
     /**
-     * Get the colour of the modem light.
+     * Get the colour of the pocket computer's light.
      *
      * See {@link #setLight(int)} for the values this may return.
      *
-     * @return The colour of the modem light.
+     * @return The colour of the pocket computer's light.
      * @see #setLight(int)
      */
     int getLight();
 
     /**
-     * Set the colour of the modem light. Use {@link 0} to turn it off.
+     * Set the colour of the pocket computer's light. Use {@link 0} to turn it off.
      *
      * Colours take the form of an integer between 0 and 15, using the opposite order to those in
      * {@link <a href="http://www.computercraft.info/wiki/Colors_(API)#Colors">The colors API</a>}  - so 0 being black,
@@ -45,31 +45,32 @@ public interface IPocketAccess
     void setLight( int value );
 
     /**
-     * Get the upgrade specific NBT
+     * Get the upgrade-specific NBT.
      *
-     * @return The upgrade's NBT
+     * This is persisted between computer reboots and chunk loads.
+     *
+     * @return The upgrade's NBT.
      * @see #updateUpgradeNBTData()
      */
     @Nonnull
     NBTTagCompound getUpgradeNBTData();
 
     /**
-     * Mark the upgrade specific NBT as dirty
+     * Mark the upgrade-specific NBT as dirty.
      *
      * @see #getUpgradeNBTData()
      */
     void updateUpgradeNBTData();
 
     /**
-     * Remove the current peripheral and create a new one. You
-     * may wish to do this if the methods available change.
+     * Remove the current peripheral and create a new one. You may wish to do this if the methods available change.
      */
     void invalidatePeripheral();
 
     /**
-     * Get a list of all upgrades for the pocket computer
+     * Get a list of all upgrades for the pocket computer.
      *
-     * @return A collection of all upgrade names
+     * @return A collection of all upgrade names.
      */
     @Nonnull
     Map<ResourceLocation, IPeripheral> getUpgrades();

src/main/java/dan200/computercraft/api/pocket/IPocketUpgrade.java

@@ -2,9 +2,7 @@ package dan200.computercraft.api.pocket;
 
 import dan200.computercraft.api.ComputerCraftAPI;
 import dan200.computercraft.api.peripheral.IPeripheral;
-import dan200.computercraft.api.turtle.ITurtleAccess;
 import dan200.computercraft.api.turtle.ITurtleUpgrade;
-import dan200.computercraft.api.turtle.TurtleSide;
 import net.minecraft.item.ItemStack;
 import net.minecraft.util.ResourceLocation;
 import net.minecraft.world.World;
@@ -14,18 +12,20 @@ import javax.annotation.Nullable;
 
 /**
  * Additional peripherals for pocket computers.
- * <p>
+ *
  * This is similar to {@link dan200.computercraft.api.turtle.ITurtleUpgrade}.
  */
 public interface IPocketUpgrade
 {
 
     /**
-     * Gets a unique identifier representing this type of turtle upgrade. eg: "computercraft:wireless_modem" or "my_mod:my_upgrade".
-     * You should use a unique resource domain to ensure this upgrade is uniquely identified.
-     * The peripheral will fail registration if an already used ID is specified.
+     * Gets a unique identifier representing this type of turtle upgrade. eg: "computercraft:wireless_modem" or
+     * "my_mod:my_upgrade".
      *
-     * @return The id
+     * You should use a unique resource domain to ensure this upgrade is uniquely identified. The upgrade will fail
+     * registration if an already used ID is specified.
+     *
+     * @return The upgrade's id.
      * @see IPocketUpgrade#getUpgradeID()
      * @see ComputerCraftAPI#registerPocketUpgrade(IPocketUpgrade)
      */
@@ -33,54 +33,59 @@ public interface IPocketUpgrade
     ResourceLocation getUpgradeID();
 
     /**
-     * Return a String to describe this type of turtle in turtle item names.
-     * An example of built-in adjectives is "Wireless".
+     * Return an unlocalised string to describe the type of pocket computer this upgrade provides.
      *
-     * @return The unlocalised adjective
+     * An example of a built-in adjectives is "Wireless" - this is converted to "Wireless Pocket Computer".
+     *
+     * @return The unlocalised adjective.
      * @see ITurtleUpgrade#getUnlocalisedAdjective()
      */
     @Nonnull
     String getUnlocalisedAdjective();
 
     /**
-     * Return an item stack representing the type of item that a turtle must be crafted
-     * with to create a turtle which holds this upgrade. This item stack is also used
-     * to determine the upgrade given by turtle.equip()
+     * Return an item stack representing the type of item that a pocket computer must be crafted with to create a
+     * pocket computer which holds this upgrade. This item stack is also used to determine the upgrade given by
+     * {@code pocket.equip()}/{@code pocket.unequip()}.
      *
      * @return The item stack used for crafting. This can be {@code null} if crafting is disabled.
-     * @see ITurtleUpgrade#getCraftingItem()
      */
     @Nullable
     ItemStack getCraftingItem();
 
     /**
      * Creates a peripheral for the pocket computer.
-     * <p>
-     * The peripheral created will be stored for the lifetime of the upgrade, will have update() called
-     * once-per-tick, and will be attached, detached and have methods called in the same manner as a Computer peripheral.
      *
-     * @param access The access object for the pocket item stack
+     * The peripheral created will be stored for the lifetime of the upgrade, will be passed an argument to
+     * {@link #update(IPocketAccess, IPeripheral)} and will be attached, detached and have methods called in the same
+     * manner as an ordinary peripheral.
+     *
+     * @param access The access object for the pocket item stack.
      * @return The newly created peripheral.
-     * @see ITurtleUpgrade#createPeripheral(ITurtleAccess, TurtleSide)
+     * @see #update(IPocketAccess, IPeripheral)
      */
     @Nullable
     IPeripheral createPeripheral( @Nonnull IPocketAccess access );
 
     /**
-     * Called when the pocket computer item stack updates
+     * Called when the pocket computer item stack updates.
      *
-     * @param access     The access object for the pocket item stack
-     * @param peripheral The peripheral for this upgrade
+     * @param access     The access object for the pocket item stack.
+     * @param peripheral The peripheral for this upgrade.
+     * @see #createPeripheral(IPocketAccess)
      */
     void update( @Nonnull IPocketAccess access, @Nullable IPeripheral peripheral );
 
     /**
-     * Called when the pocket computer is right clicked on something
+     * Called when the pocket computer is right clicked.
      *
-     * @param world      The world the computer is in
-     * @param access     The access object for the pocket item stack
-     * @param peripheral The peripheral for this upgrade
-     * @return {@code true} to stop the gui from opening, otherwise false.
+     * @param world      The world the computer is in.
+     * @param access     The access object for the pocket item stack.
+     * @param peripheral The peripheral for this upgrade.
+     * @return {@code true} to stop the GUI from opening, otherwise false. You should always provide some code path
+     * which returns {@code false}, such as requiring the player to be sneaking - otherwise they will be unable to
+     * access the GUI.
+     * @see #createPeripheral(IPocketAccess)
      */
     boolean onRightClick( @Nonnull World world, @Nonnull IPocketAccess access, @Nullable IPeripheral peripheral );
 }