mirrors/CC-Tweaked
1
0
Fork 0
mirror of https://github.com/SquidDev-CC/CC-Tweaked synced 2024-12-04 15:29:58 +00:00
Code Issues Releases Wiki Activity

"Finish" documentation for several modules

Browse Source 
- 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 2021-04-03 12:44:22 +01:00
parent 9708dd6786
commit 51d3b091da
6 changed files with 183 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
doc/stub/turtle.lua
View File

@ -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

21
illuaminate.sexp
View File

@ -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
src/main/java/dan200/computercraft/shared/peripheral/generic/methods/FluidMethods.java
View File

@ -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,

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

@ -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
* `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.

118
src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java
View File

@ -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()
{

1
src/main/resources/data/computercraft/lua/rom/apis/turtle/turtle.lua
View File

@ -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)