From fb9590467df8d9e12563401893027811680fbbb5 Mon Sep 17 00:00:00 2001
From: Jonathan Coates <git@squiddev.cc>
Date: Tue, 4 May 2021 19:23:35 +0100
Subject: [PATCH] Add some examples to inventory methods

Closes #761. It's not perfect, but it's a little better. Maybe??
---
 .../generic/methods/InventoryMethods.java     | 32 ++++++++++++++++++-
 .../shared/turtle/apis/TurtleAPI.java         |  2 ++
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/InventoryMethods.java b/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/InventoryMethods.java
index 64e342b30..e86bc8901 100644
--- a/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/InventoryMethods.java
+++ b/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/InventoryMethods.java
@@ -63,7 +63,8 @@ public class InventoryMethods implements GenericSource
      *
      * 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}.
+     * with {@link #getItemDetail}. The table contains the item `name`, the `count` and an a (potentially nil) hash of
+     * the item's `nbt.` This NBT data doesn't contain anything useful, but allows you to distinguish identical items.
      *
      * The returned table is sparse, and so empty slots will be `nil` - it is recommended to loop over using `pairs`
      * rather than `ipairs`.
@@ -71,6 +72,14 @@ public class InventoryMethods implements GenericSource
      * @param inventory The current inventory.
      * @return All items in this inventory.
      * @cc.treturn { (table|nil)... } All items in this inventory.
+     * @cc.usage Find an adjacent chest and print all items in it.
+     *
+     * <pre>{@code
+     * local chest = peripheral.find("minecraft:chest")
+     * for slot, item in pairs(chest.list()) do
+     *   print(("%d x %s in slot %d"):format(item.count, item.name, slot))
+     * end
+     * }</pre>
      */
     @LuaFunction( mainThread = true )
     public static Map<Integer, Map<String, ?>> list( IItemHandler inventory )
@@ -89,11 +98,32 @@ public class InventoryMethods implements GenericSource
     /**
      * Get detailed information about an item.
      *
+     * The returned information contains the same information as each item in
+     * {@link #list}, as well as additional details like the display name
+     * (`displayName`) and item durability (`damage`, `maxDamage`, `durability`).
+     *
+     * Some items include more information (such as enchantments) - it is
+     * recommended to print it out using @{textutils.serialize} or in the Lua
+     * REPL, to explore what is available.
+     *
      * @param inventory The current inventory.
      * @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.
+     * @cc.usage Print some information about the first in a chest.
+     *
+     * <pre>{@code
+     * local chest = peripheral.find("minecraft:chest")
+     * local item = chest.getItemDetail(1)
+     * if not item then print("No item") return end
+     *
+     * print(("%s (%s)"):format(item.displayName, item.name))
+     * print(("Count: %d/%d"):format(item.count, item.maxCount))
+     * if item.damage then
+     *   print(("Damage: %d/%d"):format(item.damage, item.maxDamage))
+     * end
+     * }</pre>
      */
     @Nullable
     @LuaFunction( mainThread = true )
diff --git a/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java b/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java
index 6c87be3d2..78d56ad6c 100644
--- a/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java
+++ b/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java
@@ -16,6 +16,7 @@ import dan200.computercraft.core.apis.IAPIEnvironment;
 import dan200.computercraft.core.asm.TaskCallback;
 import dan200.computercraft.core.tracking.TrackingField;
 import dan200.computercraft.shared.peripheral.generic.data.ItemData;
+import dan200.computercraft.shared.peripheral.generic.methods.InventoryMethods;
 import dan200.computercraft.shared.turtle.core.*;
 import net.minecraft.item.ItemStack;
 import net.minecraftforge.common.MinecraftForge;
@@ -702,6 +703,7 @@ public class TurtleAPI implements ILuaAPI
      *                 more information about the item at the cost of taking longer to run.
      * @return The command result.
      * @throws LuaException If the slot is out of range.
+     * @see InventoryMethods#getItemDetail Describes the information returned by a detailed query.
      * @cc.treturn nil|table Information about the given slot, or {@code nil} if it is empty.
      * @cc.usage Print the current slot, assuming it contains 13 dirt.
      *