"Finish" documentation for several modules

- Add remaining docs for the turtle API
 - Add documentation for the fluid storage peripheral.
 - Enforce undocumented warning for most modules (only io and window
   remaining).

"Finish" in quotes, because these are clearly a long way from perfect.
I'm bad at writing docs, OK!

doc/stub/turtle.lua

@@ -1 +1,13 @@
+--[[- Craft a recipe based on the turtle's inventory.
+
+The turtle's inventory should set up like a crafting grid. For instance, to
+craft sticks, slots 1 and 5 should contain sticks. _All_ other slots should be
+empty, including those outside the crafting "grid".
+
+@tparam[opt=64] number limit The maximum number of crafting steps to run.
+@throws When limit is less than 1 or greater than 64.
+@treturn[1] true If crafting succeeds.
+@treturn[2] false If crafting fails.
+@treturn string A string describing why crafting failed.
+]]
 function craft(limit) end

illuaminate.sexp

@@ -88,27 +88,16 @@
 
 ;; Suppress warnings for currently undocumented modules.
 (at
-  (; Java APIs
+  (; Lua APIs
-   /doc/stub/http.lua
-   /doc/stub/os.lua
-   /doc/stub/turtle.lua
-   /doc/stub/global.lua
-   ; Java generated APIs
-   /build/docs/luaJavadoc/turtle.lua
-   ; Peripherals
-   /build/docs/luaJavadoc/drive.lua
-   /build/docs/luaJavadoc/speaker.lua
-   /build/docs/luaJavadoc/printer.lua
-   ; Generic peripherals
-   /build/docs/luaJavadoc/fluid_storage.lua
-   ; Lua APIs
    /src/main/resources/*/computercraft/lua/rom/apis/io.lua
    /src/main/resources/*/computercraft/lua/rom/apis/window.lua)
 
   (linters -doc:undocumented -doc:undocumented-arg -doc:undocumented-return))
 
-;; Suppress warnings for the BIOS using its own deprecated members for now.
+;; Suppress warnings for various APIs using its own deprecated members.
-(at /src/main/resources/*/computercraft/lua/bios.lua
+(at
+  (/src/main/resources/*/computercraft/lua/bios.lua
+   /src/main/resources/*/computercraft/lua/rom/apis/turtle/turtle.lua)
   (linters -var:deprecated))
 
 (at /src/test/resources/test-rom

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

@@ -45,6 +45,19 @@ public class FluidMethods implements GenericSource
         return new ResourceLocation( ForgeVersion.MOD_ID, "fluid" );
     }
 
+    /**
+     * Get all "tanks" in this fluid storage.
+     *
+     * Each tank either contains some amount of fluid or is empty. Tanks with fluids inside will return some basic
+     * information about the fluid, including its name and amount.
+     *
+     * The returned table is sparse, and so empty tanks will be `nil` - it is recommended to loop over using `pairs`
+     * rather than `ipairs`.
+     *
+     * @param fluids The current fluid handler.
+     * @return All tanks.
+     * @cc.treturn { (table|nil)... } All tanks in this fluid storage.
+     */
     @LuaFunction( mainThread = true )
     public static Map<Integer, Map<String, ?>> tanks( IFluidHandler fluids )
     {
@@ -59,6 +72,22 @@ public class FluidMethods implements GenericSource
         return result;
     }
 
+    /**
+     * Move a fluid from one fluid container to another connected one.
+     *
+     * This allows you to pull fluid in the current fluid container to another container <em>on the same wired
+     * network</em>. Both containers must attached to wired modems which are connected via a cable.
+     *
+     * @param from      Container to move fluid from.
+     * @param computer  The current computer.
+     * @param toName    The name of the peripheral/container to push to. This is the string given to @{peripheral.wrap},
+     *                  and displayed by the wired modem.
+     * @param limit     The maximum amount of fluid to move.
+     * @param fluidName The fluid to move. If not given, an arbitrary fluid will be chosen.
+     * @return The amount of moved fluid.
+     * @throws LuaException If the peripheral to transfer to doesn't exist or isn't an fluid container.
+     * @cc.see peripheral.getName Allows you to get the name of a @{peripheral.wrap|wrapped} peripheral.
+     */
     @LuaFunction( mainThread = true )
     public static int pushFluid(
         IFluidHandler from, IComputerAccess computer,
@@ -84,6 +113,22 @@ public class FluidMethods implements GenericSource
             : moveFluid( from, new FluidStack( fluid, actualLimit ), to );
     }
 
+    /**
+     * Move a fluid from a connected fluid container into this oneone.
+     *
+     * This allows you to pull fluid in the current fluid container from another container <em>on the same wired
+     * network</em>. Both containers must attached to wired modems which are connected via a cable.
+     *
+     * @param to        Container to move fluid to.
+     * @param computer  The current computer.
+     * @param fromName  The name of the peripheral/container to push to. This is the string given to @{peripheral.wrap},
+     *                  and displayed by the wired modem.
+     * @param limit     The maximum amount of fluid to move.
+     * @param fluidName The fluid to move. If not given, an arbitrary fluid will be chosen.
+     * @return The amount of moved fluid.
+     * @throws LuaException If the peripheral to transfer to doesn't exist or isn't an fluid container.
+     * @cc.see peripheral.getName Allows you to get the name of a @{peripheral.wrap|wrapped} peripheral.
+     */
     @LuaFunction( mainThread = true )
     public static int pullFluid(
         IFluidHandler to, IComputerAccess computer,

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

@@ -65,8 +65,8 @@ public class InventoryMethods implements GenericSource
      * {@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
+     * The returned table is sparse, and so empty slots will be `nil` - it is recommended to loop over using `pairs`
-     * `ipairs`.
+     * rather than `ipairs`.
      *
      * @param inventory The current inventory.
      * @return All items in this inventory.

src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java

@@ -371,18 +371,36 @@ public class TurtleAPI implements ILuaAPI
         return trackCommand( new TurtleDetectCommand( InteractDirection.DOWN ) );
     }
 
+    /**
+     * Check if the block in front of the turtle is equal to the item in the currently selected slot.
+     *
+     * @return If the block and item are equal.
+     * @cc.treturn boolean If the block and item are equal.
+     */
     @LuaFunction
     public final MethodResult compare()
     {
         return trackCommand( new TurtleCompareCommand( InteractDirection.FORWARD ) );
     }
 
+    /**
+     * Check if the block above the turtle is equal to the item in the currently selected slot.
+     *
+     * @return If the block and item are equal.
+     * @cc.treturn boolean If the block and item are equal.
+     */
     @LuaFunction
     public final MethodResult compareUp()
     {
         return trackCommand( new TurtleCompareCommand( InteractDirection.UP ) );
     }
 
+    /**
+     * Check if the block below the turtle is equal to the item in the currently selected slot.
+     *
+     * @return If the block and item are equal.
+     * @cc.treturn boolean If the block and item are equal.
+     */
     @LuaFunction
     public final MethodResult compareDown()
     {
@@ -478,12 +496,57 @@ public class TurtleAPI implements ILuaAPI
         return trackCommand( new TurtleSuckCommand( InteractDirection.DOWN, checkCount( count ) ) );
     }
 
+    /**
+     * Get the maximum amount of fuel this turtle currently holds.
+     *
+     * @return The fuel level, or "unlimited".
+     * @cc.treturn[1] number The current amount of fuel a turtle this turtle has.
+     * @cc.treturn[2] "unlimited" If turtles do not consume fuel when moving.
+     * @see #getFuelLimit()
+     * @see #refuel(Optional)
+     */
     @LuaFunction
     public final Object getFuelLevel()
     {
         return turtle.isFuelNeeded() ? turtle.getFuelLevel() : "unlimited";
     }
 
+    /**
+     * Refuel this turtle.
+     *
+     * While most actions a turtle can perform (such as digging or placing blocks), moving consumes fuel from the
+     * turtle's internal buffer. If a turtle has no fuel, it will not move.
+     *
+     * {@link #refuel} refuels the turtle, consuming fuel items (such as coal or lava buckets) from the currently
+     * selected slot and converting them into energy. This finishes once the turtle is fully refuelled or all items have
+     * been consumed.
+     *
+     * @param countA The maximum number of items to consume. One can pass `0` to check if an item is combustable or not.
+     * @return If this turtle could be refuelled.
+     * @throws LuaException If the refuel count is out of range.
+     * @cc.treturn[1] true If the turtle was refuelled.
+     * @cc.treturn[2] false If the turtle was not refuelled.
+     * @cc.treturn[2] string The reason the turtle was not refuelled (
+     * @cc.usage Refuel a turtle from the currently selected slot.
+     * <pre>{@code
+     * local level = turtle.getFuelLevel()
+     * if new_level == "unlimited" then error("Turtle does not need fuel", 0) end
+     *
+     * local ok, err = turtle.refuel()
+     * if ok then
+     *   local new_level = turtle.getFuelLevel()
+     *   print(("Refuelled %d, current level is %d"):format(new_level - level, new_level))
+     * else
+     *   printError(err)
+     * end}</pre>
+     * @cc.usage Check if the current item is a valid fuel source.
+     * <pre>{@code
+     * local is_fuel, reason = turtle.refuel(0)
+     * if not is_fuel then printError(reason) end
+     * }</pre>
+     * @see #getFuelLevel()
+     * @see #getFuelLimit()
+     */
     @LuaFunction
     public final MethodResult refuel( Optional<Integer> countA ) throws LuaException
     {
@@ -492,12 +555,30 @@ public class TurtleAPI implements ILuaAPI
         return trackCommand( new TurtleRefuelCommand( count ) );
     }
 
+    /**
+     * Compare the item in the currently selected slot to the item in another slot.
+     *
+     * @param slot The slot to compare to.
+     * @return If the items are the same.
+     * @throws LuaException If the slot is out of range.
+     * @cc.treturn boolean If the two items are equal.
+     */
     @LuaFunction
     public final MethodResult compareTo( int slot ) throws LuaException
     {
         return trackCommand( new TurtleCompareToCommand( checkSlot( slot ) ) );
     }
 
+    /**
+     * Move an item from the selected slot to another one.
+     *
+     * @param slotArg  The slot to move this item to.
+     * @param countArg The maximum number of items to move.
+     * @return If the item was moved or not.
+     * @throws LuaException If the slot is out of range.
+     * @throws LuaException If the number of items is out of range.
+     * @cc.treturn boolean If some items were successfully moved.
+     */
     @LuaFunction
     public final MethodResult transferTo( int slotArg, Optional<Integer> countArg ) throws LuaException
     {
@@ -518,18 +599,55 @@ public class TurtleAPI implements ILuaAPI
         return turtle.getSelectedSlot() + 1;
     }
 
+    /**
+     * Get the maximum amount of fuel this turtle can hold.
+     *
+     * By default, normal turtles have a limit of 20,000 and advanced turtles of 100,000.
+     *
+     * @return The limit, or "unlimited".
+     * @cc.treturn[1] number The maximum amount of fuel a turtle can hold.
+     * @cc.treturn[2] "unlimited" If turtles do not consume fuel when moving.
+     * @see #getFuelLevel()
+     * @see #refuel(Optional)
+     */
     @LuaFunction
     public final Object getFuelLimit()
     {
         return turtle.isFuelNeeded() ? turtle.getFuelLimit() : "unlimited";
     }
 
+    /**
+     * Equip (or unequip) an item on the left side of this turtle.
+     *
+     * This finds the item in the currently selected slot and attempts to equip it to the left side of the turtle. The
+     * previous upgrade is removed and placed into the turtle's inventory. If there is no item in the slot, the previous
+     * upgrade is removed, but no new one is equipped.
+     *
+     * @return Whether an item was equiped or not.
+     * @cc.treturn[1] true If the item was equipped.
+     * @cc.treturn[2] false If we could not equip the item.
+     * @cc.treturn[2] string The reason equipping this item failed.
+     * @see #equipRight()
+     */
     @LuaFunction
     public final MethodResult equipLeft()
     {
         return trackCommand( new TurtleEquipCommand( TurtleSide.LEFT ) );
     }
 
+    /**
+     * Equip (or unequip) an item on the right side of this turtle.
+     *
+     * This finds the item in the currently selected slot and attempts to equip it to the right side of the turtle. The
+     * previous upgrade is removed and placed into the turtle's inventory. If there is no item in the slot, the previous
+     * upgrade is removed, but no new one is equipped.
+     *
+     * @return Whether an item was equiped or not.
+     * @cc.treturn[1] true If the item was equipped.
+     * @cc.treturn[2] false If we could not equip the item.
+     * @cc.treturn[2] string The reason equipping this item failed.
+     * @see #equipRight()
+     */
     @LuaFunction
     public final MethodResult equipRight()
     {

src/main/resources/data/computercraft/lua/rom/apis/turtle/turtle.lua

@@ -10,6 +10,7 @@ end
 --
 -- Generally you should not need to use this table - it only exists for
 -- backwards compatibility reasons.
+-- @deprecated
 native = turtle.native or turtle
 
 local function addCraftMethod(object)