Docs for energy and inventory methods

The inventory transfer methods really need a proper tutorial with
screenshots and everything else, but this is a good starting point, I
guess.

illuaminate.sexp

@@ -93,9 +93,7 @@
    /build/docs/luaJavadoc/speaker.lua
    /build/docs/luaJavadoc/printer.lua
    ; Generic peripherals
-   /build/docs/luaJavadoc/energy_storage.lua
    /build/docs/luaJavadoc/fluid_storage.lua
-   /build/docs/luaJavadoc/inventory.lua
    ; Lua APIs
    /src/main/resources/*/computercraft/lua/rom/apis/io.lua
    /src/main/resources/*/computercraft/lua/rom/apis/window.lua)

src/main/java/dan200/computercraft/shared/peripheral/generic/methods/EnergyMethods.java

@@ -18,6 +18,13 @@ import javax.annotation.Nonnull;
 /**
  * Methods for interacting with blocks using Forge's energy storage system.
  *
+ * This works with energy storage blocks, as well as generators and machines which consume energy.
+ *
+ * <blockquote>
+ * <strong>Note:</strong> Due to limitations with Forge's energy API, it is not possible to measure throughput (i.e. RF
+ * used/generated per tick).
+ * </blockquote>
+ *
  * @cc.module energy_storage
  */
 @AutoService( GenericSource.class )
@@ -30,12 +37,22 @@ public class EnergyMethods implements GenericSource
         return new ResourceLocation( ForgeVersion.MOD_ID, "energy" );
     }
 
+    /**
+     * Get the energy of this block.
+     *
+     * @return The energy stored in this block, in FE.
+     */
     @LuaFunction( mainThread = true )
     public static int getEnergy( IEnergyStorage energy )
     {
         return energy.getEnergyStored();
     }
 
+    /**
+     * Get the maximum amount of energy this block can store.
+     *
+     * @return The energy capacity of this block.
+     */
     @LuaFunction( mainThread = true )
     public static int getEnergyCapacity( IEnergyStorage energy )
     {

src/main/java/dan200/computercraft/shared/peripheral/generic/methods/InventoryMethods.java

@@ -47,12 +47,30 @@ public class InventoryMethods implements GenericSource
         return new ResourceLocation( ForgeVersion.MOD_ID, "inventory" );
     }
 
+    /**
+     * Get the size of this inventory.
+     *
+     * @return The number of slots in this inventory.
+     */
     @LuaFunction( mainThread = true )
     public static int size( IItemHandler inventory )
     {
         return inventory.getSlots();
     }
 
+    /**
+     * List all items in this inventory. This returns a table, with an entry for each slot.
+     *
+     * Each item in the inventory is represented by a table containing some basic information, much like
+     * {@link dan200.computercraft.shared.turtle.apis.TurtleAPI#getItemDetail} includes. More information can be fetched
+     * with {@link #getItemDetail}.
+     *
+     * The table is sparse, and so empty slots will be `nil` - it is recommended to loop over using `pairs` rather than
+     * `ipairs`.
+     *
+     * @return All items in this inventory.
+     * @cc.treturn { (table|nil)... } All items in this inventory.
+     */
     @LuaFunction( mainThread = true )
     public static Map<Integer, Map<String, ?>> list( IItemHandler inventory )
     {
@@ -67,6 +85,15 @@ public class InventoryMethods implements GenericSource
         return result;
     }
 
+    /**
+     * Get detailed information about an item.
+     *
+     * @param slot The slot to get information about.
+     * @return Information about the item in this slot, or {@code nil} if not present.
+     * @throws LuaException If the slot is out of range.
+     * @cc.treturn table Information about the item in this slot, or {@code nil} if not present.
+     */
+    @Nullable
     @LuaFunction( mainThread = true )
     public static Map<String, ?> getItemDetail( IItemHandler inventory, int slot ) throws LuaException
     {
@@ -76,6 +103,30 @@ public class InventoryMethods implements GenericSource
         return stack.isEmpty() ? null : ItemData.fill( new HashMap<>(), stack );
     }
 
+    /**
+     * Push items from one inventory to another connected one.
+     *
+     * This allows you to push an item in an inventory to another inventory <em>on the same wired network</em>. Both
+     * inventories must attached to wired modems which are connected via a cable.
+     *
+     * @param toName The name of the peripheral/inventory to push to. This is the string given to @{peripheral.wrap},
+     * and displayed by the wired modem.
+     * @param fromSlot The slot in the current inventory to move items to.
+     * @param limit The maximum number of items to move. Defaults to the current stack limit.
+     * @param toSlot The slot in the target inventory to move to. If not given, the item will be inserted into any slot.
+     * @return The number of transferred items.
+     * @throws LuaException If the peripheral to transfer to doesn't exist or isn't an inventory.
+     * @throws LuaException If either source or destination slot is out of range.
+     *
+     * @cc.see peripheral.getName Allows you to get the name of a @{peripheral.wrap|wrapped} peripheral.
+     * @cc.usage Wrap two chests, and push an item from one to another.
+     * <pre>{@code
+     * local chest_a = peripheral.wrap("minecraft:chest_0")
+     * local chest_b = peripheral.wrap("minecraft:chest_0")
+     *
+     * chest_a.pushItems(peripheral.getName(chest_b), 1)
+     * }</pre>
+     */
     @LuaFunction( mainThread = true )
     public static int pushItems(
         IItemHandler from, IComputerAccess computer,
@@ -91,13 +142,37 @@ public class InventoryMethods implements GenericSource
 
         // Validate slots
         int actualLimit = limit.orElse( Integer.MAX_VALUE );
-        if( actualLimit <= 0 ) throw new LuaException( "Limit must be > 0" );
         assertBetween( fromSlot, 1, from.getSlots(), "From slot out of range (%s)" );
         if( toSlot.isPresent() ) assertBetween( toSlot.get(), 1, to.getSlots(), "To slot out of range (%s)" );
 
+        if( actualLimit <= 0 ) return 0;
         return moveItem( from, fromSlot - 1, to, toSlot.orElse( 0 ) - 1, actualLimit );
     }
 
+    /**
+     * Pull items from a connected inventory into this one.
+     *
+     * This allows you to transfer items between inventories <em>on the same wired network</em>. Both this and the source
+     * inventory must attached to wired modems which are connected via a cable.
+     *
+     * @param fromName The name of the peripheral/inventory to pull from. This is the string given to @{peripheral.wrap},
+     * and displayed by the wired modem.
+     * @param fromSlot The slot in the source inventory to move items from.
+     * @param limit The maximum number of items to move. Defaults to the current stack limit.
+     * @param toSlot The slot in current inventory to move to. If not given, the item will be inserted into any slot.
+     * @return The number of transferred items.
+     * @throws LuaException If the peripheral to transfer to doesn't exist or isn't an inventory.
+     * @throws LuaException If either source or destination slot is out of range.
+     *
+     * @cc.see peripheral.getName Allows you to get the name of a @{peripheral.wrap|wrapped} peripheral.
+     * @cc.usage Wrap two chests, and push an item from one to another.
+     * <pre>{@code
+     * local chest_a = peripheral.wrap("minecraft:chest_0")
+     * local chest_b = peripheral.wrap("minecraft:chest_0")
+     *
+     * chest_a.pullItems(peripheral.getName(chest_b), 1)
+     * }</pre>
+     */
     @LuaFunction( mainThread = true )
     public static int pullItems(
         IItemHandler to, IComputerAccess computer,
@@ -113,10 +188,10 @@ public class InventoryMethods implements GenericSource
 
         // Validate slots
         int actualLimit = limit.orElse( Integer.MAX_VALUE );
-        if( actualLimit <= 0 ) throw new LuaException( "Limit must be > 0" );
         assertBetween( fromSlot, 1, from.getSlots(), "From slot out of range (%s)" );
         if( toSlot.isPresent() ) assertBetween( toSlot.get(), 1, to.getSlots(), "To slot out of range (%s)" );
 
+        if( actualLimit <= 0 ) return 0;
         return moveItem( from, fromSlot - 1, to, toSlot.orElse( 0 ) - 1, actualLimit );
     }