"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!
This commit is contained in:
Jonathan Coates
parent
9708dd6786
commit
51d3b091da
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -88,27 +88,16 @@
|
|||
|
||||
;; Suppress warnings for currently undocumented modules.
|
||||
(at
|
||||
(; Java 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
|
||||
(; 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.
|
||||
(at /src/main/resources/*/computercraft/lua/bios.lua
|
||||
;; Suppress warnings for various APIs using its own deprecated members.
|
||||
(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
|
||||
|
|
|
|||
|
|
@ -45,6 +45,19 @@ public ResourceLocation id()
|
|||
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 ResourceLocation id()
|
|||
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 static int pushFluid(
|
|||
: 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,
|
||||
|
|
|
|||
|
|
@ -65,8 +65,8 @@ public static int size( IItemHandler inventory )
|
|||
* {@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`.
|
||||
* The returned table is sparse, and so empty slots will be `nil` - it is recommended to loop over using `pairs`
|
||||
* rather than `ipairs`.
|
||||
*
|
||||
* @param inventory The current inventory.
|
||||
* @return All items in this inventory.
|
||||
|
|
|
|||
|
|
@ -371,18 +371,36 @@ public final MethodResult detectDown()
|
|||
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 final MethodResult suckDown( Optional<Integer> count ) throws LuaExceptio
|
|||
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 final MethodResult refuel( Optional<Integer> countA ) throws LuaException
|
|||
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 final int getSelectedSlot()
|
|||
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()
|
||||
{
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
Loading…
Reference in New Issue