mirrors/CC-Tweaked
1
0
Fork 0
mirror of https://github.com/SquidDev-CC/CC-Tweaked synced 2025-10-30 21:23:00 +00:00
Code Issues Releases Wiki Activity

Some improvements to Javadoc publishing

Browse Source 
- Use <p> everywhere. This is uglier, but also technically more
   correct. This requires a version bump to cct-javadoc, and will give
   me a massive headache when merging.

 - Link against the existing OpenJDK docs.
This commit is contained in:
Jonathan Coates
2022-10-25 19:17:55 +01:00
parent af7af615c7
commit f45614175a
101 changed files with 287 additions and 286 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
build.gradle.kts
View File

@@ -149,6 +149,7 @@ illuaminate {
tasks.javadoc {
include("dan200/computercraft/api/**/*.java")
(options as StandardJavadocDocletOptions).links("https://docs.oracle.com/javase/8/docs/api/")
}
val apiJar by tasks.registering(Jar::class) {

2
gradle/libs.versions.toml
View File

@@ -18,7 +18,7 @@ jqwik = "1.7.0"
junit = "5.9.1"
# Build tools
cctJavadoc = "1.5.0"
cctJavadoc = "1.5.1"
checkstyle = "8.25" # There's a reason we're pinned on an ancient version, but I can't remember what it is.
curseForgeGradle = "1.0.11"
forgeGradle = "5.1.+"

12
src/main/java/dan200/computercraft/api/ComputerCraftAPI.java
View File

@@ -38,7 +38,7 @@ import javax.annotation.Nullable;
/**
* The static entry point to the ComputerCraft API.
*
* <p>
* Members in this class must be called after mod_ComputerCraft has been initialised, but may be called before it is
* fully loaded.
*/
@@ -59,13 +59,13 @@ public final class ComputerCraftAPI
/**
* Creates a numbered directory in a subfolder of the save directory for a given world, and returns that number.
*
* <p>
* Use in conjunction with createSaveDirMount() to create a unique place for your peripherals or media items to store files.
*
* @param world The world for which the save dir should be created. This should be the server side world object.
* @param parentSubPath The folder path within the save directory where the new directory should be created. eg: "computercraft/disk"
* @return The numerical value of the name of the new folder, or -1 if the folder could not be created for some reason.
*
* <p>
* eg: if createUniqueNumberedSaveDir( world, "computer/disk" ) was called returns 42, then "computer/disk/42" is now
* available for writing.
* @see #createSaveDirMount(World, String, long)
@@ -77,7 +77,7 @@ public final class ComputerCraftAPI
/**
* Creates a file system mount that maps to a subfolder of the save directory for a given world, and returns it.
*
* <p>
* Use in conjunction with IComputerAccess.mount() or IComputerAccess.mountWritable() to mount a folder from the
* users save directory onto a computers file system.
*
@@ -101,10 +101,10 @@ public final class ComputerCraftAPI
/**
* Creates a file system mount to a resource folder, and returns it.
*
* <p>
* Use in conjunction with {@link IComputerAccess#mount} or {@link IComputerAccess#mountWritable} to mount a
* resource folder onto a computer's file system.
*
* <p>
* The files in this mount will be a combination of files in all mod jar, and data packs that contain
* resources with the same domain and path. For instance, ComputerCraft's resources are stored in
* "/data/computercraft/lua/rom". We construct a mount for that with

10
src/main/java/dan200/computercraft/api/IUpgradeBase.java
View File

@@ -21,7 +21,7 @@ public interface IUpgradeBase
/**
* Gets a unique identifier representing this type of turtle upgrade. eg: "computercraft:wireless_modem"
* or "my_mod:my_upgrade".
*
* <p>
* You should use a unique resource domain to ensure this upgrade is uniquely identified.
* The upgrade will fail registration if an already used ID is specified.
*
@@ -32,7 +32,7 @@ public interface IUpgradeBase
/**
* Return an unlocalised string to describe this type of computer in item names.
*
* <p>
* Examples of built-in adjectives are "Wireless", "Mining" and "Crafty".
*
* @return The localisation key for this upgrade's adjective.
@@ -44,7 +44,7 @@ public interface IUpgradeBase
* Return an item stack representing the type of item that a computer must be crafted
* with to create a version which holds this upgrade. This item stack is also used
* to determine the upgrade given by {@code turtle.equipLeft()} or {@code pocket.equipBack()}
*
* <p>
* This should be constant over a session (or at least a datapack reload). It is recommended
* that you cache the stack too, in order to prevent constructing it every time the method
* is called.
@@ -56,11 +56,11 @@ public interface IUpgradeBase
/**
* Determine if an item is suitable for being used for this upgrade.
*
* <p>
* When un-equipping an upgrade, we return {@link #getCraftingItem()} rather than
* the original stack. In order to prevent people losing items with enchantments (or
* repairing items with non-0 damage), we impose additional checks on the item.
*
* <p>
* The default check requires that any non-capability NBT is exactly the same as the
* crafting item, but this may be relaxed for your upgrade.
*

2
src/main/java/dan200/computercraft/api/detail/BasicItemDetailProvider.java
View File

@@ -49,7 +49,7 @@ public abstract class BasicItemDetailProvider<T> implements IDetailProvider<Item
/**
* Provide additional details for the given {@link Item} and {@link ItemStack}. This method is called by
* {@code turtle.getItemDetail()}. New properties should be added to the given {@link Map}, {@code data}.
*
* <p>
* This method is always called on the server thread, so it is safe to interact with the world here, but you should
* take care to avoid long blocking operations as this will stall the server and other computers.
*

2
src/main/java/dan200/computercraft/api/filesystem/FileOperationException.java
View File

@@ -12,7 +12,7 @@ import java.util.Objects;
/**
* An {@link IOException} which occurred on a specific file.
*
* <p>
* This may be thrown from a {@link IMount} or {@link IWritableMount} to give more information about a failure.
*/
public class FileOperationException extends IOException

2
src/main/java/dan200/computercraft/api/filesystem/IFileSystem.java
View File

@@ -9,7 +9,7 @@ import java.io.IOException;
/**
* Provides a mount of the entire computer's file system.
*
* <p>
* This exists for use by various APIs - one should not attempt to mount it.
*/
public interface IFileSystem extends IWritableMount

2
src/main/java/dan200/computercraft/api/filesystem/IMount.java
View File

@@ -18,7 +18,7 @@ import java.util.List;
/**
* Represents a read only part of a virtual filesystem that can be mounted onto a computer using
* {@link IComputerAccess#mount(String, IMount)}.
*
* <p>
* Ready made implementations of this interface can be created using
* {@link ComputerCraftAPI#createSaveDirMount(World, String, long)} or
* {@link ComputerCraftAPI#createResourceMount(String, String)}, or you're free to implement it yourselves!

2
src/main/java/dan200/computercraft/api/filesystem/IWritableMount.java
View File

@@ -18,7 +18,7 @@ import java.util.OptionalLong;
/**
* Represents a part of a virtual filesystem that can be mounted onto a computer using {@link IComputerAccess#mount(String, IMount)}
* or {@link IComputerAccess#mountWritable(String, IWritableMount)}, that can also be written to.
*
* <p>
* Ready made implementations of this interface can be created using
* {@link ComputerCraftAPI#createSaveDirMount(World, String, long)}, or you're free to implement it yourselves!
*

8
src/main/java/dan200/computercraft/api/lua/GenericSource.java
View File

@@ -17,17 +17,17 @@ import javax.annotation.Nonnull;
/**
* A generic source of {@link LuaMethod} functions.
*
* <p>
* Unlike normal objects ({@link IDynamicLuaObject} or {@link IPeripheral}), methods do not target this object but
* instead are defined as {@code static} and accept their target as the first parameter. This allows you to inject
* methods onto objects you do not own, as well as declaring methods for a specific "trait" (for instance, a
* {@link Capability}).
*
* <p>
* Currently the "generic peripheral" system is incompatible with normal peripherals. Normal {@link IPeripheralProvider}
* or {@link IPeripheral} implementations take priority. Tile entities which use this system are given a peripheral name
* determined by their id, rather than any peripheral provider. This will hopefully change in the future, once a suitable
* design has been established.
*
* <p>
* For example, the main CC: Tweaked mod defines a generic source for inventories, which works on {@link IItemHandler}s:
*
* <pre>{@code
@@ -49,7 +49,7 @@ public interface GenericSource
{
/**
* A unique identifier for this generic source.
*
* <p>
* This is currently unused, but may be used in the future to allow disabling specific sources. It is recommended
* to return an identifier using your mod's ID.
*

6
src/main/java/dan200/computercraft/api/lua/IArguments.java
View File

@@ -185,7 +185,7 @@ public interface IArguments
/**
* Get an argument as a table in an unsafe manner.
*
* <p>
* Classes implementing this interface may choose to implement a more optimised version which does not copy the
* table, instead returning a wrapper version, making it more efficient. However, the caller must guarantee that
* they do not access the table the computer thread (and so should not be used with main-thread functions) or once
@@ -334,7 +334,7 @@ public interface IArguments
/**
* Get an argument as a table in an unsafe manner.
*
* <p>
* Classes implementing this interface may choose to implement a more optimised version which does not copy the
* table, instead returning a wrapper version, making it more efficient. However, the caller must guarantee that
* they do not access off the computer thread (and so should not be used with main-thread functions) or once the
@@ -446,7 +446,7 @@ public interface IArguments
/**
* This is called when the current function finishes, before any main thread tasks have run.
*
* <p>
* Called when the current function returns, and so some values are no longer guaranteed to be safe to access.
*
* @deprecated This method was an internal implementation detail and is no longer used.

2
src/main/java/dan200/computercraft/api/lua/IDynamicLuaObject.java
View File

@@ -11,7 +11,7 @@ import javax.annotation.Nonnull;
/**
* An interface for representing custom objects returned by peripherals or other Lua objects.
*
* <p>
* Generally, one does not need to implement this type - it is sufficient to return an object with some methods
* annotated with {@link LuaFunction}. {@link IDynamicLuaObject} is useful when you wish your available methods to
* change at runtime.

6
src/main/java/dan200/computercraft/api/lua/ILuaAPI.java
View File

@@ -10,7 +10,7 @@ import dan200.computercraft.api.ComputerCraftAPI;
/**
* Represents a Lua object which is stored as a global variable on computer startup. This must either provide
* {@link LuaFunction} annotated functions or implement {@link IDynamicLuaObject}.
*
* <p>
* Before implementing this interface, consider alternative methods of providing methods. It is generally preferred
* to use peripherals to provide functionality to users.
*
@@ -28,7 +28,7 @@ public interface ILuaAPI
/**
* Called when the computer is turned on.
*
* <p>
* One should only interact with the file system.
*/
default void startup()
@@ -44,7 +44,7 @@ public interface ILuaAPI
/**
* Called when the computer is turned off or unloaded.
*
* <p>
* This should reset the state of the object, disposing any remaining file handles, or other resources.
*/
default void shutdown()

4
src/main/java/dan200/computercraft/api/lua/ILuaContext.java
View File

@@ -17,7 +17,7 @@ public interface ILuaContext
* Queue a task to be executed on the main server thread at the beginning of next tick, but do not wait for it to
* complete. This should be used when you need to interact with the world in a thread-safe manner but do not care
* about the result or you wish to run asynchronously.
*
* <p>
* When the task has finished, it will enqueue a {@code task_completed} event, which takes the task id, a success
* value and the return values, or an error message if it failed.
*
@@ -31,7 +31,7 @@ public interface ILuaContext
/**
* Queue a task to be executed on the main server thread at the beginning of next tick, waiting for it to complete.
* This should be used when you need to interact with the world in a thread-safe manner.
*
* <p>
* Note that the return values of your task are handled as events, meaning more complex objects such as maps or
* {@link IDynamicLuaObject} will not preserve their identities.
*

8
src/main/java/dan200/computercraft/api/lua/LuaFunction.java
View File

@@ -14,7 +14,7 @@ import java.util.Optional;
/**
* Used to mark a Java function which is callable from Lua.
*
* <p>
* Methods annotated with {@link LuaFunction} must be public final instance methods. They can have any number of
* parameters, but they must be of the following types:
*
@@ -24,12 +24,12 @@ import java.util.Optional;
* <li>
* Alternatively, one may specify the desired arguments as normal parameters and the argument parsing code will
* be generated automatically.
*
* <p>
* Each parameter must be one of the given types supported by {@link IArguments} (for instance, {@link int} or
* {@link Map}). Optional values are supported by accepting a parameter of type {@link Optional}.
* </li>
* </ul>
*
* <p>
* This function may return {@link MethodResult}. However, if you simply return a value (rather than having to yield),
* you may return {@code void}, a single value (either an object or a primitive like {@code int}) or array of objects.
* These will be treated the same as {@link MethodResult#of()}, {@link MethodResult#of(Object)} and
@@ -58,7 +58,7 @@ public @interface LuaFunction
/**
* Allow using "unsafe" arguments, such {@link IArguments#getTableUnsafe(int)}.
*
* <p>
* This is incompatible with {@link #mainThread()}.
*
* @return Whether this function supports unsafe arguments.

6
src/main/java/dan200/computercraft/api/lua/MethodResult.java
View File

@@ -16,7 +16,7 @@ import java.util.Objects;
/**
* The result of invoking a Lua method.
*
* <p>
* Method results either return a value immediately ({@link #of(Object...)} or yield control to the parent coroutine.
* When the current coroutine is resumed, we invoke the provided {@link ILuaCallback#resume(Object[])} callback.
*/
@@ -55,11 +55,11 @@ public final class MethodResult
/**
* Return a single value immediately.
*
* <p>
* Integers, doubles, floats, strings, booleans, {@link Map}, {@link Collection}s, arrays and {@code null} will be
* converted to their corresponding Lua type. {@code byte[]} and {@link ByteBuffer} will be treated as binary
* strings. {@link ILuaFunction} will be treated as a function.
*
* <p>
* In order to provide a custom object with methods, one may return a {@link IDynamicLuaObject}, or an arbitrary
* class with {@link LuaFunction} annotations. Anything else will be converted to {@code nil}.
*

2
src/main/java/dan200/computercraft/api/media/IMedia.java
View File

@@ -16,7 +16,7 @@ import javax.annotation.Nullable;
/**
* Represents an item that can be placed in a disk drive and used by a Computer.
*
* <p>
* Implement this interface on your {@link Item} class to allow it to be used in the drive. Alternatively, register
* a {@link IMediaProvider}.
*/

4
src/main/java/dan200/computercraft/api/network/IPacketReceiver.java
View File

@@ -33,7 +33,7 @@ public interface IPacketReceiver
/**
* Get the maximum distance this receiver can send and receive messages.
*
* <p>
* When determining whether a receiver can receive a message, the largest distance of the packet and receiver is
* used - ensuring it is within range. If the packet or receiver is inter-dimensional, then the packet will always
* be received.
@@ -47,7 +47,7 @@ public interface IPacketReceiver
/**
* Determine whether this receiver can receive packets from other dimensions.
*
* <p>
* A device will receive an inter-dimensional packet if either it or the sending device is inter-dimensional.
*
* @return Whether this receiver receives packets from other dimensions.

4
src/main/java/dan200/computercraft/api/network/wired/IWiredElement.java
View File

@@ -11,11 +11,11 @@ import javax.annotation.Nonnull;
/**
* An object which may be part of a wired network.
*
* <p>
* Elements should construct a node using {@link ComputerCraftAPI#createWiredNodeForElement(IWiredElement)}. This acts
* as a proxy for all network objects. Whilst the node may change networks, an element's node should remain constant
* for its lifespan.
*
* <p>
* Elements are generally tied to a block or tile entity in world. In such as case, one should provide the
* {@link IWiredElement} capability for the appropriate sides.
*/

12
src/main/java/dan200/computercraft/api/network/wired/IWiredNetwork.java
View File

@@ -13,12 +13,12 @@ import java.util.Map;
/**
* A wired network is composed of one of more {@link IWiredNode}s, a set of connections between them, and a series
* of peripherals.
*
* <p>
* Networks from a connected graph. This means there is some path between all nodes on the network. Further more, if
* there is some path between two nodes then they must be on the same network. {@link IWiredNetwork} will automatically
* handle the merging and splitting of networks (and thus changing of available nodes and peripherals) as connections
* change.
*
* <p>
* This does mean one can not rely on the network remaining consistent between subsequent operations. Consequently,
* it is generally preferred to use the methods provided by {@link IWiredNode}.
*
@@ -28,7 +28,7 @@ public interface IWiredNetwork
{
/**
* Create a connection between two nodes.
*
* <p>
* This should only be used on the server thread.
*
* @param left The first node to connect
@@ -43,7 +43,7 @@ public interface IWiredNetwork
/**
* Destroy a connection between this node and another.
*
* <p>
* This should only be used on the server thread.
*
* @param left The first node in the connection.
@@ -58,7 +58,7 @@ public interface IWiredNetwork
/**
* Sever all connections this node has, removing it from this network.
*
* <p>
* This should only be used on the server thread. You should only call this on nodes
* that your network element owns.
*
@@ -72,7 +72,7 @@ public interface IWiredNetwork
/**
* Update the peripherals a node provides.
*
* <p>
* This should only be used on the server thread. You should only call this on nodes
* that your network element owns.
*

16
src/main/java/dan200/computercraft/api/network/wired/IWiredNode.java
View File

@@ -13,14 +13,14 @@ import java.util.Map;
/**
* Wired nodes act as a layer between {@link IWiredElement}s and {@link IWiredNetwork}s.
*
* <p>
* Firstly, a node acts as a packet network, capable of sending and receiving modem messages to connected nodes. These
* methods may be safely used on any thread.
*
* <p>
* When sending a packet, the system will attempt to find the shortest path between the two nodes based on their
* element's position. Note that packet senders and receivers can have different locations from their associated
* element: the distance between the two will be added to the total packet's distance.
*
* <p>
* Wired nodes also provide several convenience methods for interacting with a wired network. These should only ever
* be used on the main server thread.
*/
@@ -37,7 +37,7 @@ public interface IWiredNode extends IPacketNetwork
/**
* The network this node is currently connected to. Note that this may change
* after any network operation, so it should not be cached.
*
* <p>
* This should only be used on the server thread.
*
* @return This node's network.
@@ -47,7 +47,7 @@ public interface IWiredNode extends IPacketNetwork
/**
* Create a connection from this node to another.
*
* <p>
* This should only be used on the server thread.
*
* @param node The other node to connect to.
@@ -62,7 +62,7 @@ public interface IWiredNode extends IPacketNetwork
/**
* Destroy a connection between this node and another.
*
* <p>
* This should only be used on the server thread.
*
* @param node The other node to disconnect from.
@@ -78,7 +78,7 @@ public interface IWiredNode extends IPacketNetwork
/**
* Sever all connections this node has, removing it from this network.
*
* <p>
* This should only be used on the server thread. You should only call this on nodes
* that your network element owns.
*
@@ -94,7 +94,7 @@ public interface IWiredNode extends IPacketNetwork
/**
* Mark this node's peripherals as having changed.
*
* <p>
* This should only be used on the server thread. You should only call this on nodes
* that your network element owns.
*

4
src/main/java/dan200/computercraft/api/network/wired/IWiredSender.java
View File

@@ -11,7 +11,7 @@ import javax.annotation.Nonnull;
/**
* An object on a {@link IWiredNetwork} capable of sending packets.
*
* <p>
* Unlike a regular {@link IPacketSender}, this must be associated with the node you are attempting to
* to send the packet from.
*/
@@ -19,7 +19,7 @@ public interface IWiredSender extends IPacketSender
{
/**
* The node in the network representing this object.
*
* <p>
* This should be used as a proxy for the main network. One should send packets
* and register receivers through this object.
*

8
src/main/java/dan200/computercraft/api/peripheral/GenericPeripheral.java
View File

@@ -13,7 +13,7 @@ import javax.annotation.Nonnull;
/**
* A {@link GenericSource} which provides methods for a peripheral.
*
* <p>
* Unlike a {@link GenericSource}, all methods <strong>should</strong> target the same type, for instance a
* {@link TileEntity} subclass or a capability interface. This is not currently enforced.
*/
@@ -21,13 +21,13 @@ public interface GenericPeripheral extends GenericSource
{
/**
* Get the type of the exposed peripheral.
*
* <p>
* Unlike normal {@link IPeripheral}s, {@link GenericPeripheral} do not have to have a type. By default, the
* resulting peripheral uses the resource name of the wrapped {@link TileEntity} (for instance {@code minecraft:chest}).
*
* <p>
* However, in some cases it may be more appropriate to specify a more readable name. Overriding this method allows
* you to do so.
*
* <p>
* When multiple {@link GenericPeripheral}s return a non-empty peripheral type for a single tile entity, the
* lexicographically smallest will be chosen. In order to avoid this conflict, this method should only be
* implemented when your peripheral targets a single tile entity <strong>AND</strong> it's likely that you're the

14
src/main/java/dan200/computercraft/api/peripheral/IComputerAccess.java
View File

@@ -105,11 +105,11 @@ public interface IComputerAccess
/**
* Unmounts a directory previously mounted onto the computers file system by {@link #mount(String, IMount)}
* or {@link #mountWritable(String, IWritableMount)}.
*
* <p>
* When a directory is unmounted, it will disappear from the computers file system, and the user will no longer be
* able to access it. All directories mounted by a mount or mountWritable are automatically unmounted when the
* peripheral is attached if they have not been explicitly unmounted.
*
* <p>
* Note that you cannot unmount another peripheral's mounts.
*
* @param location The desired location in the computers file system of the directory to unmount.
@@ -124,7 +124,7 @@ public interface IComputerAccess
/**
* Returns the numerical ID of this computer.
*
* <p>
* This is the same number obtained by calling {@code os.getComputerID()} or running the "id" program from lua,
* and is guaranteed unique. This number will be positive.
*
@@ -145,7 +145,7 @@ public interface IComputerAccess
* @param arguments In addition to a name, you may pass an array of extra arguments to the event, that will
* be supplied as extra return values to os.pullEvent(). Objects in the array will be converted
* to lua data types in the same fashion as the return values of IPeripheral.callMethod().
*
* <p>
* You may supply {@code null} to indicate that no arguments are to be supplied.
* @throws NotAttachedException If the peripheral has been detached.
* @see MethodResult#pullEvent(String, ILuaCallback)
@@ -167,7 +167,7 @@ public interface IComputerAccess
/**
* Get a set of peripherals that this computer access can "see", along with their attachment name.
*
* <p>
* This may include other peripherals on the wired network or peripherals on other sides of the computer.
*
* @return All reachable peripherals
@@ -191,12 +191,12 @@ public interface IComputerAccess
/**
* Get a {@link IWorkMonitor} for tasks your peripheral might execute on the main (server) thread.
*
* <p>
* This should be used to ensure your peripheral integrates with ComputerCraft's monitoring and limiting of how much
* server time each computer consumes. You should not need to use this if you use
* {@link ILuaContext#issueMainThreadTask(ILuaTask)} - this is intended for mods with their own system for running
* work on the main thread.
*
* <p>
* Please note that the returned implementation is <em>not</em> thread-safe, and should only be used from the main
* thread.
*

4
src/main/java/dan200/computercraft/api/peripheral/IDynamicPeripheral.java
View File

@@ -11,7 +11,7 @@ import javax.annotation.Nonnull;
/**
* A peripheral whose methods are not known at runtime.
*
* <p>
* This behaves similarly to {@link IDynamicLuaObject}, though also accepting the current {@link IComputerAccess}.
* Generally one may use {@link LuaFunction} instead of implementing this interface.
*/
@@ -30,7 +30,7 @@ public interface IDynamicPeripheral extends IPeripheral
/**
* This is called when a lua program on an attached computer calls {@code peripheral.call()} with
* one of the methods exposed by {@link #getMethodNames()}.
*
* <p>
* Be aware that this will be called from the ComputerCraft Lua thread, and must be thread-safe when interacting
* with Minecraft objects.
*

18
src/main/java/dan200/computercraft/api/peripheral/IPeripheral.java
View File

@@ -15,10 +15,10 @@ import java.util.Set;
/**
* The interface that defines a peripheral.
*
* <p>
* In order to expose a peripheral for your block or tile entity, you may either attach a {@link Capability}, or
* register a {@link IPeripheralProvider}. This <em>cannot</em> be implemented {@link IPeripheral} directly on the tile.
*
* <p>
* Peripherals should provide a series of methods to the user, either using {@link LuaFunction} or by implementing
* {@link IDynamicPeripheral}.
*/
@@ -47,15 +47,15 @@ public interface IPeripheral
/**
* Is called when when a computer is attaching to the peripheral.
*
* <p>
* This will occur when a peripheral is placed next to an active computer, when a computer is turned on next to a
* peripheral, when a turtle travels into a square next to a peripheral, or when a wired modem adjacent to this
* peripheral is does any of the above.
*
* <p>
* Between calls to attach and {@link #detach}, the attached computer can make method calls on the peripheral using
* {@code peripheral.call()}. This method can be used to keep track of which computers are attached to the
* peripheral, or to take action when attachment occurs.
*
* <p>
* Be aware that will be called from both the server thread and ComputerCraft Lua thread, and so must be thread-safe
* and reentrant.
*
@@ -69,14 +69,14 @@ public interface IPeripheral
/**
* Called when a computer is detaching from the peripheral.
*
* <p>
* This will occur when a computer shuts down, when the peripheral is removed while attached to computers, when a
* turtle moves away from a block attached to a peripheral, or when a wired modem adjacent to this peripheral is
* detached.
*
* <p>
* This method can be used to keep track of which computers are attached to the peripheral, or to take action when
* detachment occurs.
*
* <p>
* Be aware that this will be called from both the server and ComputerCraft Lua thread, and must be thread-safe
* and reentrant.
*
@@ -102,7 +102,7 @@ public interface IPeripheral
/**
* Determine whether this peripheral is equivalent to another one.
*
* <p>
* The minimal example should at least check whether they are the same object. However, you may wish to check if
* they point to the same block or tile entity.
*

2
src/main/java/dan200/computercraft/api/peripheral/IPeripheralProvider.java
View File

@@ -15,7 +15,7 @@ import javax.annotation.Nonnull;
/**
* This interface is used to create peripheral implementations for blocks.
*
* <p>
* If you have a {@link TileEntity} which acts as a peripheral, you may alternatively expose the {@link IPeripheral}
* capability.
*

8
src/main/java/dan200/computercraft/api/peripheral/IWorkMonitor.java
View File

@@ -12,14 +12,14 @@ import java.util.concurrent.TimeUnit;
/**
* Monitors "work" associated with a computer, keeping track of how much a computer has done, and ensuring every
* computer receives a fair share of any processing time.
*
* <p>
* This is primarily intended for work done by peripherals on the main thread (such as on a tile entity's tick), but
* could be used for other purposes (such as complex computations done on another thread).
*
* <p>
* Before running a task, one should call {@link #canWork()} to determine if the computer is currently allowed to
* execute work. If that returns true, you should execute the task and use {@link #trackWork(long, TimeUnit)} to inform
* the monitor how long that task took.
*
* <p>
* Alternatively, use {@link #runWork(Runnable)} to run and keep track of work.
*
* @see IComputerAccess#getMainThreadMonitor()
@@ -35,7 +35,7 @@ public interface IWorkMonitor
/**
* If the owning computer is currently allowed to execute work, and has ample time to do so.
*
* <p>
* This is effectively a more restrictive form of {@link #canWork()}. One should use that in order to determine if
* you may do an initial piece of work, and shouldWork to determine if any additional task may be performed.
*

2
src/main/java/dan200/computercraft/api/peripheral/PeripheralType.java
View File

@@ -16,7 +16,7 @@ import java.util.Set;
/**
* The type of a {@link GenericPeripheral}.
*
* <p>
* When determining the final type of the resulting peripheral, the union of all types is taken, with the
* lexicographically smallest non-empty name being chosen.
*/

2
src/main/java/dan200/computercraft/api/pocket/AbstractPocketUpgrade.java
View File

@@ -17,7 +17,7 @@ import java.util.function.Supplier;
/**
* A base class for {@link IPocketUpgrade}s.
*
* <p>
* One does not have to use this, but it does provide a convenient template.
*/
public abstract class AbstractPocketUpgrade implements IPocketUpgrade

4
src/main/java/dan200/computercraft/api/pocket/IPocketAccess.java
View File

@@ -21,7 +21,7 @@ public interface IPocketAccess
{
/**
* Gets the entity holding this item.
*
* <p>
* This must be called on the server thread.
*
* @return The holding entity, or {@code null} if none exists.
@@ -67,7 +67,7 @@ public interface IPocketAccess
/**
* Get the upgrade-specific NBT.
*
* <p>
* This is persisted between computer reboots and chunk loads.
*
* @return The upgrade's NBT.

2
src/main/java/dan200/computercraft/api/pocket/IPocketUpgrade.java
View File

@@ -22,7 +22,7 @@ public interface IPocketUpgrade extends IUpgradeBase
{
/**
* Creates a peripheral for the pocket computer.
*
* <p>
* The peripheral created will be stored for the lifetime of the upgrade, will be passed an argument to
* {@link #update(IPocketAccess, IPeripheral)} and will be attached, detached and have methods called in the same
* manner as an ordinary peripheral.

4
src/main/java/dan200/computercraft/api/turtle/AbstractTurtleUpgrade.java
View File

@@ -17,7 +17,7 @@ import java.util.function.Supplier;
/**
* A base class for {@link ITurtleUpgrade}s.
*
* <p>
* One does not have to use this, but it does provide a convenient template.
*/
public abstract class AbstractTurtleUpgrade implements ITurtleUpgrade
@@ -100,7 +100,7 @@ public abstract class AbstractTurtleUpgrade implements ITurtleUpgrade
/**
* A supplier which converts an item into an item stack.
*
* <p>
* Constructing item stacks is somewhat expensive due to attaching capabilities. We cache it if given a consistent item.
*/
private static final class CachedStack implements NonNullSupplier<ItemStack>

10
src/main/java/dan200/computercraft/api/turtle/ITurtleAccess.java
View File

@@ -22,7 +22,7 @@ import javax.annotation.Nullable;
/**
* The interface passed to turtle by turtles, providing methods that they can call.
*
* <p>
* This should not be implemented by your classes. Do not interact with turtles except via this interface and
* {@link ITurtleUpgrade}.
*/
@@ -46,7 +46,7 @@ public interface ITurtleAccess
/**
* Attempt to move this turtle to a new position.
*
* <p>
* This will preserve the turtle's internal state, such as it's inventory, computer and upgrades. It should
* be used before playing a movement animation using {@link #playAnimation(TurtleAnimation)}.
*
@@ -144,7 +144,7 @@ public interface ITurtleAccess
/**
* Get the inventory of this turtle.
*
* <p>
* Note: this inventory should only be accessed and modified on the server thread.
*
* @return This turtle's inventory
@@ -155,7 +155,7 @@ public interface ITurtleAccess
/**
* Get the inventory of this turtle as an {@link IItemHandlerModifiable}.
*
* <p>
* Note: this inventory should only be accessed and modified on the server thread.
*
* @return This turtle's inventory
@@ -278,7 +278,7 @@ public interface ITurtleAccess
/**
* Get an upgrade-specific NBT compound, which can be used to store arbitrary data.
*
* <p>
* This will be persisted across turtle restarts and chunk loads, as well as being synced to the client. You must
* call {@link #updateUpgradeNBTData(TurtleSide)} after modifying it.
*

2
src/main/java/dan200/computercraft/api/turtle/ITurtleCommand.java
View File

@@ -17,7 +17,7 @@ public interface ITurtleCommand
{
/**
* Will be called by the turtle on the main thread when it is time to execute the custom command.
*
* <p>
* The handler should either perform the work of the command, and return success, or return
* failure with an error message to indicate the command cannot be executed at this time.
*

6
src/main/java/dan200/computercraft/api/turtle/ITurtleUpgrade.java
View File

@@ -41,7 +41,7 @@ public interface ITurtleUpgrade extends IUpgradeBase
/**
* Will only be called for peripheral upgrades. Creates a peripheral for a turtle being placed using this upgrade.
*
* <p>
* The peripheral created will be stored for the lifetime of the upgrade and will be passed as an argument to
* {@link #update(ITurtleAccess, TurtleSide)}. It will be attached, detached and have methods called in the same
* manner as a Computer peripheral.
@@ -60,7 +60,7 @@ public interface ITurtleUpgrade extends IUpgradeBase
/**
* Will only be called for Tool turtle. Called when turtle.dig() or turtle.attack() is called
* by the turtle, and the tool is required to do some work.
*
* <p>
* Conforming implementations should fire {@link BlockEvent.BreakEvent} and {@link TurtleBlockEvent.Dig} for
* digging, {@link AttackEntityEvent} and {@link TurtleAttackEvent} for attacking.
*
@@ -83,7 +83,7 @@ public interface ITurtleUpgrade extends IUpgradeBase
/**
* Called to obtain the model to be used when rendering a turtle peripheral.
*
* <p>
* This can be obtained from {@link net.minecraft.client.renderer.ItemModelMesher#getItemModel(ItemStack)},
* {@link net.minecraft.client.renderer.model.ModelManager#getModel(ModelResourceLocation)} or any other
* source.

2
src/main/java/dan200/computercraft/api/turtle/TurtleAnimation.java
View File

@@ -7,7 +7,7 @@ package dan200.computercraft.api.turtle;
/**
* An animation a turtle will play between executing commands.
*
* <p>
* Each animation takes 8 ticks to complete unless otherwise specified.
*
* @see ITurtleAccess#playAnimation(TurtleAnimation)

4
src/main/java/dan200/computercraft/api/turtle/event/TurtleActionEvent.java
View File

@@ -37,7 +37,7 @@ public class TurtleActionEvent extends TurtleEvent
/**
* Sets the cancellation state of this action.
*
* <p>
* If {@code cancel} is {@code true}, this action will not be carried out.
*
* @param cancel The new canceled value.
@@ -53,7 +53,7 @@ public class TurtleActionEvent extends TurtleEvent
/**
* Set the cancellation state of this action, setting a failure message if required.
*
* <p>
* If {@code cancel} is {@code true}, this action will not be carried out.
*
* @param cancel The new canceled value.

4
src/main/java/dan200/computercraft/api/turtle/event/TurtleAttackEvent.java
View File

@@ -19,10 +19,10 @@ import java.util.Objects;
/**
* Fired when a turtle attempts to attack an entity.
*
* <p>
* This must be fired by {@link ITurtleUpgrade#useTool(ITurtleAccess, TurtleSide, TurtleVerb, Direction)},
* as the base {@code turtle.attack()} command does not fire it.
*
* <p>
* Note that such commands should also fire {@link AttackEntityEvent}, so you do not need to listen to both.
*
* @see TurtleAction#ATTACK

12
src/main/java/dan200/computercraft/api/turtle/event/TurtleBlockEvent.java
View File

@@ -24,13 +24,13 @@ import java.util.Objects;
/**
* A general event for when a turtle interacts with a block or region.
*
* <p>
* You should generally listen to one of the sub-events instead, cancelling them where
* appropriate.
*
* <p>
* Note that you are not guaranteed to receive this event, if it has been cancelled by other
* mechanisms, such as block protection systems.
*
* <p>
* Be aware that some events (such as {@link TurtleInventoryEvent}) do not necessarily interact
* with a block, simply objects within that block space.
*/
@@ -72,10 +72,10 @@ public abstract class TurtleBlockEvent extends TurtlePlayerEvent
/**
* Fired when a turtle attempts to dig a block.
*
* <p>
* This must be fired by {@link ITurtleUpgrade#useTool(ITurtleAccess, TurtleSide, TurtleVerb, Direction)},
* as the base {@code turtle.dig()} command does not fire it.
*
* <p>
* Note that such commands should also fire {@link BlockEvent.BreakEvent}, so you do not need to listen to both.
*
* @see TurtleAction#DIG
@@ -176,7 +176,7 @@ public abstract class TurtleBlockEvent extends TurtlePlayerEvent
/**
* Fired when a turtle gathers data on a block in world.
*
* <p>
* You may prevent blocks being inspected, or add additional information to the result.
*
* @see TurtleAction#INSPECT

2
src/main/java/dan200/computercraft/api/turtle/event/TurtleEvent.java
View File

@@ -14,7 +14,7 @@ import java.util.Objects;
/**
* A base class for all events concerning a turtle. This will only ever constructed and fired on the server side,
* so sever specific methods on {@link ITurtleAccess} are safe to use.
*
* <p>
* You should generally not need to subscribe to this event, preferring one of the more specific classes.
*
* @see TurtleActionEvent

2
src/main/java/dan200/computercraft/api/turtle/event/TurtleInspectItemEvent.java
View File

@@ -15,7 +15,7 @@ import java.util.Objects;
/**
* Fired when a turtle gathers data on an item in its inventory.
*
* <p>
* You may prevent items being inspected, or add additional information to the result. Be aware that this may be fired
* on the computer thread, and so any operations on it must be thread safe.
*

4
src/main/java/dan200/computercraft/api/turtle/event/TurtlePlayerEvent.java
View File

@@ -13,7 +13,7 @@ import java.util.Objects;
/**
* An action done by a turtle which is normally done by a player.
*
* <p>
* {@link #getPlayer()} may be used to modify the player's attributes or perform permission checks.
*/
public abstract class TurtlePlayerEvent extends TurtleActionEvent
@@ -30,7 +30,7 @@ public abstract class TurtlePlayerEvent extends TurtleActionEvent
/**
* A fake player, representing this turtle.
*
* <p>
* This may be used for triggering permission checks.
*
* @return A {@link FakePlayer} representing this turtle.

6
src/main/java/dan200/computercraft/api/turtle/event/TurtleRefuelEvent.java
View File

@@ -14,7 +14,7 @@ import java.util.Objects;
/**
* Fired when a turtle attempts to refuel from an item.
*
* <p>
* One may use {@link #setCanceled(boolean, String)} to prevent refueling from this specific item. Additionally, you
* may use {@link #setHandler(Handler)} to register a custom fuel provider.
*/
@@ -33,7 +33,7 @@ public class TurtleRefuelEvent extends TurtleActionEvent
/**
* Get the stack we are attempting to refuel from.
*
* <p>
* Do not modify the returned stack - all modifications should be done within the {@link Handler}.
*
* @return The stack to refuel from.
@@ -57,7 +57,7 @@ public class TurtleRefuelEvent extends TurtleActionEvent
/**
* Set the refuel handler for this stack.
*
* <p>
* You should call this if you can actually refuel from this item, and ideally only if there are no existing
* handlers.
*

2
src/main/java/dan200/computercraft/client/render/RenderTypes.java
View File

@@ -31,7 +31,7 @@ public class RenderTypes
/**
* Renders a fullbright terminal which also writes to the depth layer. This is used when z-fighting isn't an issue -
* for instance rendering an empty terminal or inside a GUI.
*
* <p>
* This is identical to <em>vanilla's</em> {@link RenderType#text}. Forge overrides one with a definition which sets
* sortOnUpload to true, which is entirely broken!
*/

4
src/main/java/dan200/computercraft/client/render/text/DirectFixedWidthFontRenderer.java
View File

@@ -24,14 +24,14 @@ import static org.lwjgl.system.MemoryUtil.memPutFloat;
/**
* An optimised copy of {@link FixedWidthFontRenderer} emitter emits directly to a {@link ByteBuffer} rather than
* emitting to {@link IVertexBuilder}. This allows us to emit vertices very quickly, when using the VBO renderer.
*
* <p>
* There are some limitations here:
* <ul>
* <li>No transformation matrix (not needed for VBOs).</li>
* <li>Only works with {@link DefaultVertexFormats#POSITION_COLOR_TEX}.</li>
* <li>The buffer <strong>MUST</strong> be allocated with {@link DirectBuffers}, and not through any other means.</li>
* </ul>
*
* <p>
* Note this is almost an exact copy of {@link FixedWidthFontRenderer}. While the code duplication is unfortunate,
* it is measurably faster than introducing polymorphism into {@link FixedWidthFontRenderer}.
*

2
src/main/java/dan200/computercraft/client/render/text/FixedWidthFontRenderer.java
View File

@@ -21,7 +21,7 @@ import static dan200.computercraft.client.render.RenderTypes.FULL_BRIGHT_LIGHTMA
/**
* Handles rendering fixed width text and computer terminals.
*
* <p>
* This class has several modes of usage:
* <ul>
* <li>{@link #drawString}: Drawing basic text without a terminal (such as for printouts). Unlike the other methods,

24
src/main/java/dan200/computercraft/core/apis/FSAPI.java
View File

@@ -43,20 +43,20 @@ import java.util.function.Function;
* <li>**File and directory manipulation:** For instance, moving or copying files. See {@link #makeDir}, {@link #move},
* {@link #copy} and {@link #delete}.</li>
* </ul>
*
* <p>
* :::note
* All functions in the API work on absolute paths, and do not take the @{shell.dir|current directory} into account.
* You can use @{shell.resolve} to convert a relative path into an absolute one.
* :::
*
* <p>
* ## Mounts
* While a computer can only have one hard drive and filesystem, other filesystems may be "mounted" inside it. For
* instance, the {@link dan200.computercraft.shared.peripheral.diskdrive.DiskDrivePeripheral drive peripheral} mounts
* its disk's contents at {@code "disk/"}, {@code "disk1/"}, etc...
*
* <p>
* You can see which mount a path belongs to with the {@link #getDrive} function. This returns {@code "hdd"} for the
* computer's main filesystem ({@code "/"}), {@code "rom"} for the rom ({@code "rom/"}).
*
* <p>
* Most filesystems have a limited capacity, operations which would cause that capacity to be reached (such as writing
* an incredibly large file) will fail. You can see a mount's capacity with {@link #getCapacity} and the remaining
* space with {@link #getFreeSpace}.
@@ -287,7 +287,7 @@ public class FSAPI implements ILuaAPI
/**
* Moves a file or directory from one path to another.
*
* <p>
* Any parent directories are created as needed.
*
* @param path The current file or directory to move from.
@@ -310,7 +310,7 @@ public class FSAPI implements ILuaAPI
/**
* Copies a file or directory to a new path.
*
* <p>
* Any parent directories are created as needed.
*
* @param path The file or directory to copy.
@@ -333,7 +333,7 @@ public class FSAPI implements ILuaAPI
/**
* Deletes a file or directory.
*
* <p>
* If the path points to a directory, all of the enclosed files and
* subdirectories are also deleted.
*
@@ -358,14 +358,14 @@ public class FSAPI implements ILuaAPI
/**
* Opens a file for reading or writing at a path.
*
* <p>
* The {@code mode} string can be any of the following:
* <ul>
* <li><strong>"r"</strong>: Read mode</li>
* <li><strong>"w"</strong>: Write mode</li>
* <li><strong>"a"</strong>: Append mode</li>
* </ul>
*
* <p>
* The mode may also have a "b" at the end, which opens the file in "binary
* mode". This allows you to read binary files, as well as seek within a file.
*
@@ -516,7 +516,7 @@ public class FSAPI implements ILuaAPI
/**
* Searches for files matching a string with wildcards.
*
* <p>
* This string is formatted like a normal path string, but can include any
* number of wildcards ({@code *}) to look for files matching anything.
* For example, <code>rom/&#42;/command*</code> will look for any path starting with
@@ -568,10 +568,10 @@ public class FSAPI implements ILuaAPI
/**
* Get attributes about a specific file or folder.
*
* <p>
* The returned attributes table contains information about the size of the file, whether it is a directory,
* when it was created and last modified, and whether it is read only.
*
* <p>
* The creation and modification times are given as the number of milliseconds since the UNIX epoch. This may be
* given to {@link OSAPI#date} in order to convert it to more usable form.
*

14
src/main/java/dan200/computercraft/core/apis/OSAPI.java
View File

@@ -173,7 +173,7 @@ public class OSAPI implements ILuaAPI
* Starts a timer that will run for the specified number of seconds. Once
* the timer fires, a {@code timer} event will be added to the queue with
* the ID returned from this function as the first parameter.
*
* <p>
* As with @{os.sleep|sleep}, {@code timer} will automatically be rounded up
* to the nearest multiple of 0.05 seconds, as it waits for a fixed amount
* of world ticks.
@@ -315,13 +315,13 @@ public class OSAPI implements ILuaAPI
/**
* Returns the current time depending on the string passed in. This will
* always be in the range [0.0, 24.0).
*
* <p>
* * If called with {@code ingame}, the current world time will be returned.
* This is the default if nothing is passed.
* * If called with {@code utc}, returns the hour of the day in UTC time.
* * If called with {@code local}, returns the hour of the day in the
* timezone the server is located in.
*
* <p>
* This function can also be called with a table returned from {@link #date},
* which will convert the date fields into a UNIX timestamp (number of
* seconds since 1 January 1970).
@@ -363,7 +363,7 @@ public class OSAPI implements ILuaAPI
/**
* Returns the day depending on the locale specified.
*
* <p>
* * If called with {@code ingame}, returns the number of days since the
* world was created. This is the default.
* * If called with {@code utc}, returns the number of days since 1 January
@@ -395,7 +395,7 @@ public class OSAPI implements ILuaAPI
/**
* Returns the number of milliseconds since an epoch depending on the locale.
*
* <p>
* * If called with {@code ingame}, returns the number of milliseconds since the
* world was created. This is the default.
* * If called with {@code utc}, returns the number of milliseconds since 1
@@ -446,12 +446,12 @@ public class OSAPI implements ILuaAPI
/**
* Returns a date string (or table) using a specified format string and
* optional time to format.
*
* <p>
* The format string takes the same formats as C's {@code strftime} function
* (http://www.cplusplus.com/reference/ctime/strftime/). In extension, it
* can be prefixed with an exclamation mark ({@code !}) to use UTC time
* instead of the server's local timezone.
*
* <p>
* If the format is exactly {@code *t} (optionally prefixed with {@code !}), a
* table will be returned instead. This table has fields for the year, month,
* day, hour, minute, second, day of the week, day of the year, and whether

8
src/main/java/dan200/computercraft/core/apis/RedstoneAPI.java
View File

@@ -12,7 +12,7 @@ import dan200.computercraft.core.computer.ComputerSide;
/**
* Get and set redstone signals adjacent to this computer.
*
* <p>
* The {@link RedstoneAPI} library exposes three "types" of redstone control:
* - Binary input/output ({@link #setOutput}/{@link #getInput}): These simply check if a redstone wire has any input or
* output. A signal strength of 1 and 15 are treated the same.
@@ -21,10 +21,10 @@ import dan200.computercraft.core.computer.ComputerSide;
* - Bundled cables ({@link #setBundledOutput}/{@link #getBundledInput}): These interact with "bundled" cables, such
* as those from Project:Red. These allow you to send 16 separate on/off signals. Each channel corresponds to a
* colour, with the first being @{colors.white} and the last @{colors.black}.
*
* <p>
* Whenever a redstone input changes, a @{event!redstone} event will be fired. This may be used instead of repeativly
* polling.
*
* <p>
* This module may also be referred to as {@code rs}. For example, one may call {@code rs.getSides()} instead of
* {@link #getSides}.
*
@@ -47,7 +47,7 @@ import dan200.computercraft.core.computer.ComputerSide;
* os.pullEvent("redstone") -- Wait for a change to inputs.
* end
* }</pre>
*
* <p>
* [comparator]: https://minecraft.gamepedia.com/Redstone_Comparator#Subtract_signal_strength "Redstone Comparator on
* the Minecraft wiki."
* @cc.module redstone

12
src/main/java/dan200/computercraft/core/apis/TermMethods.java
View File

@@ -39,7 +39,7 @@ public abstract class TermMethods
/**
* Write {@code text} at the current cursor position, moving the cursor to the end of the text.
*
* <p>
* Unlike functions like {@code write} and {@code print}, this does not wrap the text - it simply copies the
* text to the current terminal line.
*
@@ -61,7 +61,7 @@ public abstract class TermMethods
/**
* Move all positions up (or down) by {@code y} pixels.
*
* <p>
* Every pixel in the terminal will be replaced by the line {@code y} pixels below it. If {@code y} is negative, it
* will copy pixels from above instead.
*
@@ -245,7 +245,7 @@ public abstract class TermMethods
/**
* Determine if this terminal supports colour.
*
* <p>
* Terminals which do not support colour will still allow writing coloured text/backgrounds, but it will be
* displayed in greyscale.
*
@@ -261,10 +261,10 @@ public abstract class TermMethods
/**
* Writes {@code text} to the terminal with the specific foreground and background characters.
*
* <p>
* As with {@link #write(IArguments)}, the text will be written at the current cursor location, with the cursor
* moving to the end of the text.
*
* <p>
* {@code textColour} and {@code backgroundColour} must both be strings the same length as {@code text}. All
* characters represent a single hexadecimal digit, which is converted to one of CC's colours. For instance,
* {@code "a"} corresponds to purple.
@@ -299,7 +299,7 @@ public abstract class TermMethods
/**
* Set the palette for a specific colour.
*
* <p>
* ComputerCraft's palette system allows you to change how a specific colour should be displayed. For instance, you
* can make @{colors.red} <em>more red</em> by setting its palette to #FF0000. This does now allow you to draw more
* colours - you are still limited to 16 on the screen at one time - but you can change <em>which</em> colours are

4
src/main/java/dan200/computercraft/core/apis/handles/BinaryReadableHandle.java
View File

@@ -249,11 +249,11 @@ public class BinaryReadableHandle extends HandleGeneric
/**
* Seek to a new position within the file, changing where bytes are written to. The new position is an offset
* given by {@code offset}, relative to a start position determined by {@code whence}:
*
* <p>
* - {@code "set"}: {@code offset} is relative to the beginning of the file.
* - {@code "cur"}: Relative to the current position. This is the default.
* - {@code "end"}: Relative to the end of the file.
*
* <p>
* In case of success, {@code seek} returns the new file position from the beginning of the file.
*
* @param whence Where the offset is relative to.

4
src/main/java/dan200/computercraft/core/apis/handles/BinaryWritableHandle.java
View File

@@ -117,11 +117,11 @@ public class BinaryWritableHandle extends HandleGeneric
/**
* Seek to a new position within the file, changing where bytes are written to. The new position is an offset
* given by {@code offset}, relative to a start position determined by {@code whence}:
*
* <p>
* - {@code "set"}: {@code offset} is relative to the beginning of the file.
* - {@code "cur"}: Relative to the current position. This is the default.
* - {@code "end"}: Relative to the end of the file.
*
* <p>
* In case of success, {@code seek} returns the new file position from the beginning of the file.
*
* @param whence Where the offset is relative to.

2
src/main/java/dan200/computercraft/core/apis/handles/HandleGeneric.java
View File

@@ -39,7 +39,7 @@ public abstract class HandleGeneric
/**
* Close this file, freeing any resources it uses.
*
* <p>
* Once a file is closed it may no longer be read or written to.
*
* @throws LuaException If the file has already been closed.

2
src/main/java/dan200/computercraft/core/apis/http/CheckUrl.java
View File

@@ -13,7 +13,7 @@ import java.util.concurrent.Future;
/**
* Checks a URL using {@link NetworkUtils#getAddress(String, int, boolean)}}
*
* <p>
* This requires a DNS lookup, and so needs to occur off-thread.
*/
public class CheckUrl extends Resource<CheckUrl>

4
src/main/java/dan200/computercraft/core/apis/http/NetworkUtils.java
View File

@@ -126,7 +126,7 @@ public final class NetworkUtils
/**
* Create a {@link InetSocketAddress} from a {@link java.net.URI}.
*
* <p>
* Note, this may require a DNS lookup, and so should not be executed on the main CC thread.
*
* @param uri The URI to fetch.
@@ -141,7 +141,7 @@ public final class NetworkUtils
/**
* Create a {@link InetSocketAddress} from the resolved {@code host} and port.
*
* <p>
* Note, this may require a DNS lookup, and so should not be executed on the main CC thread.
*
* @param host The host to resolve.

2
src/main/java/dan200/computercraft/core/apis/http/Resource.java
View File

@@ -68,7 +68,7 @@ public abstract class Resource<T extends Resource<T>> implements Closeable
/**
* Clean up any pending resources
*
* <p>
* Note, this may be called multiple times, and so should be thread-safe and
* avoid any major side effects.
*/

2
src/main/java/dan200/computercraft/core/asm/ObjectSource.java
View File

@@ -9,7 +9,7 @@ import java.util.function.BiConsumer;
/**
* A Lua object which exposes additional methods.
*
* <p>
* This can be used to merge multiple objects together into one. Ideally this'd be part of the API, but I'm not entirely
* happy with the interface - something I'd like to think about first.
*/

2
src/main/java/dan200/computercraft/core/computer/Environment.java
View File

@@ -22,7 +22,7 @@ import java.util.Iterator;
/**
* Represents the "environment" that a {@link Computer} exists in.
*
* <p>
* This handles storing and updating of peripherals and redstone.
*
* <h1>Redstone</h1>

10
src/main/java/dan200/computercraft/core/computer/TimeoutState.java
View File

@@ -12,18 +12,18 @@ import java.util.concurrent.TimeUnit;
/**
* Used to measure how long a computer has executed for, and thus the relevant timeout states.
*
* <p>
* Timeouts are mostly used for execution of Lua code: we should ideally never have a state where constructing the APIs
* or machines themselves takes more than a fraction of a second.
*
* <p>
* When a computer runs, it is allowed to run for 7 seconds ({@link #TIMEOUT}). After that point, the "soft abort" flag
* is set ({@link #isSoftAborted()}). Here, the Lua machine will attempt to abort the program in some safe manner
* (namely, throwing a "Too long without yielding" error).
*
* <p>
* Now, if a computer still does not stop after that period, they're behaving really badly. 1.5 seconds after a soft
* abort ({@link #ABORT_TIMEOUT}), we trigger a hard abort (note, this is done from the computer thread manager). This
* will destroy the entire Lua runtime and shut the computer down.
*
* <p>
* The Lua runtime is also allowed to pause execution if there are other computers contesting for work. All computers
* are allowed to run for {@link ComputerThread#scaledPeriod()} nanoseconds (see {@link #currentDeadline}). After that
* period, if any computers are waiting to be executed then we'll set the paused flag to true ({@link #isPaused()}.
@@ -104,7 +104,7 @@ public final class TimeoutState
/**
* Whether we should pause execution of this machine.
*
* <p>
* This is determined by whether we've consumed our time slice, and if there are other computers waiting to perform
* work.
*

2
src/main/java/dan200/computercraft/core/filesystem/ChannelWrapper.java
View File

@@ -11,7 +11,7 @@ import java.nio.channels.Channel;
/**
* Wraps some closeable object such as a buffered writer, and the underlying stream.
*
* <p>
* When flushing a buffer before closing, some implementations will not close the buffer if an exception is thrown
* this causes us to release the channel, but not actually close it. This wrapper will attempt to close the wrapper (and
* so hopefully flush the channel), and then close the underlying channel.

2
src/main/java/dan200/computercraft/core/filesystem/FileSystem.java
View File

@@ -31,7 +31,7 @@ public class FileSystem
{
/**
* Maximum depth that {@link #copyRecursive(String, MountWrapper, String, MountWrapper, int)} will descend into.
*
* <p>
* This is a pretty arbitrary value, though hopefully it is large enough that it'll never be normally hit. This
* exists to prevent it overflowing if it ever gets into an infinite loop.
*/

6
src/main/java/dan200/computercraft/core/filesystem/FileSystemWrapper.java
View File

@@ -15,12 +15,12 @@ import java.lang.ref.WeakReference;
/**
* An alternative closeable implementation that will free up resources in the filesystem.
*
* <p>
* The {@link FileSystem} maps weak references of this to its underlying object. If the wrapper has been disposed of
* (say, the Lua object referencing it has gone), then the wrapped object will be closed by the filesystem.
*
* <p>
* Closing this will stop the filesystem tracking it, reducing the current descriptor count.
*
* <p>
* In an ideal world, we'd just wrap the closeable. However, as we do some {@code instanceof} checks
* on the stream, it's not really possible as it'd require numerous instances.
*

2
src/main/java/dan200/computercraft/core/filesystem/TrackingCloseable.java
View File

@@ -10,7 +10,7 @@ import java.io.IOException;
/**
* A {@link Closeable} which knows when it has been closed.
*
* <p>
* This is a quick (though racey) way of providing more friendly (and more similar to Lua)
* error messages to the user.
*/

2
src/main/java/dan200/computercraft/core/lua/BasicFunction.java
View File

@@ -17,7 +17,7 @@ import org.squiddev.cobalt.function.VarArgFunction;
/**
* An "optimised" version of {@link ResultInterpreterFunction} which is guaranteed to never yield.
*
* <p>
* As we never yield, we do not need to push a function to the stack, which removes a small amount of overhead.
*/
class BasicFunction extends VarArgFunction

10
src/main/java/dan200/computercraft/core/lua/ILuaMachine.java
View File

@@ -15,11 +15,11 @@ import java.io.InputStream;
/**
* Represents a machine which will execute Lua code. Technically this API is flexible enough to support many languages,
* but you'd need a way to provide alternative ROMs, BIOSes, etc...
*
* <p>
* There should only be one concrete implementation at any one time, which is currently {@link CobaltLuaMachine}. If
* external mod authors are interested in registering their own machines, we can look into how we can provide some
* mechanism for registering these.
*
* <p>
* This should provide implementations of {@link dan200.computercraft.api.lua.ILuaContext}, and the ability to convert
* {@link IDynamicLuaObject}s into something the VM understands, as well as handling method calls.
*/
@@ -28,7 +28,7 @@ public interface ILuaMachine
/**
* Inject an API into the global environment of this machine. This should construct an object, as it would for any
* {@link IDynamicLuaObject} and set it to all names in {@link ILuaAPI#getNames()}.
*
* <p>
* Called before {@link #loadBios(InputStream)}.
*
* @param api The API to register.
@@ -38,7 +38,7 @@ public interface ILuaMachine
/**
* Create a function from the provided program, and set it up to run when {@link #handleEvent(String, Object[])} is
* called.
*
* <p>
* This should destroy the machine if it failed to load the bios.
*
* @param bios The stream containing the boot program.
@@ -48,7 +48,7 @@ public interface ILuaMachine
/**
* Resume the machine, either starting or resuming the coroutine.
*
* <p>
* This should destroy the machine if it failed to execute successfully.
*
* @param eventName The name of the event. This is {@code null} when first starting the machine. Note, this may

2
src/main/java/dan200/computercraft/core/lua/MachineResult.java
View File

@@ -13,7 +13,7 @@ import java.io.InputStream;
/**
* The result of executing an action on a machine.
*
* <p>
* Errors should halt the machine and display the error to the user.
*
* @see ILuaMachine#loadBios(InputStream)

2
src/main/java/dan200/computercraft/shared/CommonHooks.java
View File

@@ -33,7 +33,7 @@ import java.util.Set;
/**
* Miscellaneous hooks which are present on the client and server.
*
* <p>
* These should possibly be refactored into separate classes at some point, but are fine here for now.
*
* @see dan200.computercraft.client.ClientHooks For client-specific ones.

2
src/main/java/dan200/computercraft/shared/command/ClientCommands.java
View File

@@ -19,7 +19,7 @@ import java.io.File;
/**
* Basic client-side commands.
*
* <p>
* Simply hooks into client chat messages and intercepts matching strings.
*/
@Mod.EventBusSubscriber( modid = ComputerCraft.MOD_ID, value = Dist.CLIENT )

4
src/main/java/dan200/computercraft/shared/command/arguments/RepeatArgumentType.java
View File

@@ -30,10 +30,10 @@ import java.util.function.BiConsumer;
/**
* Reads one argument multiple times.
*
* <p>
* Note that this must be the last element in an argument chain: in order to improve the quality of error messages,
* we will always try to consume another argument while there is input remaining.
*
* <p>
* One problem with how parsers function, is that they must consume some input: and thus we
*
* @param <T> The type of each value returned

4
src/main/java/dan200/computercraft/shared/command/text/TableBuilder.java
View File

@@ -59,7 +59,7 @@ public class TableBuilder
/**
* Get the unique identifier for this table type.
*
* <p>
* When showing a table within Minecraft, previous instances of this table with
* the same ID will be removed from chat.
*
@@ -72,7 +72,7 @@ public class TableBuilder
/**
* Get the number of columns for this table.
*
* <p>
* This will be the same as {@link #getHeaders()}'s length if it is is non-{@code null},
* otherwise the length of the first column.
*

10
src/main/java/dan200/computercraft/shared/computer/apis/CommandAPI.java
View File

@@ -110,11 +110,11 @@ public class CommandAPI implements ILuaAPI
/**
* Asynchronously execute a command.
*
* <p>
* Unlike {@link #exec}, this will immediately return, instead of waiting for the
* command to execute. This allows you to run multiple commands at the same
* time.
*
* <p>
* When this command has finished executing, it will queue a `task_complete`
* event containing the result of executing this command (what {@link #exec} would
* return).
@@ -184,10 +184,10 @@ public class CommandAPI implements ILuaAPI
/**
* Get information about a range of blocks.
*
* <p>
* This returns the same information as @{getBlockInfo}, just for multiple
* blocks at once.
*
* <p>
* Blocks are traversed by ascending y level, followed by z and x - the returned
* table may be indexed using `x + z*width + y*depth*depth`.
*
@@ -245,7 +245,7 @@ public class CommandAPI implements ILuaAPI
/**
* Get some basic information about a block.
*
* <p>
* The returned table contains the current name, metadata and block state (as
* with @{turtle.inspect}). If there is a tile entity for that block, its NBT
* will also be returned.

2
src/main/java/dan200/computercraft/shared/computer/blocks/ComputerPeripheral.java
View File

@@ -14,7 +14,7 @@ import javax.annotation.Nullable;
/**
* A computer or turtle wrapped as a peripheral.
*
* <p>
* This allows for basic interaction with adjacent computers. Computers wrapped as peripherals will have the type
* {@code computer} while turtles will be {@code turtle}.
*

2
src/main/java/dan200/computercraft/shared/computer/blocks/TileComputerBase.java
View File

@@ -279,7 +279,7 @@ public abstract class TileComputerBase extends TileGeneric implements IComputerT
/**
* Update all redstone and peripherals.
*
* <p>
* This should only be really be called when the computer is being ticked (though there are some cases where it
* won't be), as peripheral scanning requires adjacent tiles to be in a "correct" state - which may not be the case
* if they're still updating!

2
src/main/java/dan200/computercraft/shared/computer/inventory/ComputerMenuWithoutInventory.java
View File

@@ -19,7 +19,7 @@ import java.util.function.Predicate;
/**
* A computer menu which does not have any visible inventory.
*
* <p>
* This adds invisible versions of the player's hotbars slots, to ensure they're synced to the client when changed.
*/
public class ComputerMenuWithoutInventory extends ContainerComputerBase

2
src/main/java/dan200/computercraft/shared/network/NetworkMessage.java
View File

@@ -20,7 +20,7 @@ public interface NetworkMessage
{
/**
* Write this packet to a buffer.
*
* <p>
* This may be called on any thread, so this should be a pure operation.
*
* @param buf The buffer to write data to.

2
src/main/java/dan200/computercraft/shared/network/client/PlayRecordClientMessage.java
View File

@@ -19,7 +19,7 @@ import javax.annotation.Nonnull;
/**
* Starts or stops a record on the client, depending on if {@link #soundEvent} is {@code null}.
*
* <p>
* Used by disk drives to play record items.
*
* @see dan200.computercraft.shared.peripheral.diskdrive.TileDiskDrive

2
src/main/java/dan200/computercraft/shared/network/client/SpeakerAudioClientMessage.java
View File

@@ -19,7 +19,7 @@ import java.util.UUID;
/**
* Starts a sound on the client.
*
* <p>
* Used by speakers to play sounds.
*
* @see dan200.computercraft.shared.peripheral.speaker.TileSpeaker

2
src/main/java/dan200/computercraft/shared/network/client/SpeakerMoveClientMessage.java
View File

@@ -18,7 +18,7 @@ import java.util.UUID;
/**
* Starts a sound on the client.
*
* <p>
* Used by speakers to play sounds.
*
* @see dan200.computercraft.shared.peripheral.speaker.TileSpeaker

2
src/main/java/dan200/computercraft/shared/network/client/SpeakerPlayClientMessage.java
View File

@@ -19,7 +19,7 @@ import java.util.UUID;
/**
* Starts a sound on the client.
*
* <p>
* Used by speakers to play sounds.
*
* @see dan200.computercraft.shared.peripheral.speaker.TileSpeaker

2
src/main/java/dan200/computercraft/shared/network/client/SpeakerStopClientMessage.java
View File

@@ -17,7 +17,7 @@ import java.util.UUID;
/**
* Stops a sound on the client
*
* <p>
* Called when a speaker is broken.
*
* @see dan200.computercraft.shared.peripheral.speaker.TileSpeaker

4
src/main/java/dan200/computercraft/shared/peripheral/commandblock/CommandBlockPeripheral.java
View File

@@ -28,10 +28,10 @@ import static dan200.computercraft.shared.Capabilities.CAPABILITY_PERIPHERAL;
/**
* This peripheral allows you to interact with command blocks.
*
* <p>
* Command blocks are only wrapped as peripherals if the {@code enable_command_block} option is true within the
* config.
*
* <p>
* This API is <em>not</em> the same as the {@link CommandAPI} API, which is exposed on command computers.
*
* @cc.module command

10
src/main/java/dan200/computercraft/shared/peripheral/diskdrive/DiskDrivePeripheral.java
View File

@@ -22,14 +22,14 @@ import java.util.Optional;
/**
* Disk drives are a peripheral which allow you to read and write to floppy disks and other "mountable media" (such as
* computers or turtles). They also allow you to {@link #playAudio play records}.
*
* <p>
* When a disk drive attaches some mount (such as a floppy disk or computer), it attaches a folder called {@code disk},
* {@code disk2}, etc... to the root directory of the computer. This folder can be used to interact with the files on
* that disk.
*
* <p>
* When a disk is inserted, a {@code disk} event is fired, with the side peripheral is on. Likewise, when the disk is
* detached, a {@code disk_eject} event is fired.
*
* <p>
* ## Recipe
* <div class="recipe-container">
* <mc-recipe recipe="computercraft:disk_drive"></mc-recipe>
@@ -80,9 +80,9 @@ public class DiskDrivePeripheral implements IPeripheral
/**
* Sets or clears the label for a disk.
*
* <p>
* If no label or {@code nil} is passed, the label will be cleared.
*
* <p>
* If the inserted disk's label can't be changed (for example, a record),
* an error will be thrown.
*

2
src/main/java/dan200/computercraft/shared/peripheral/generic/methods/ArgumentHelpers.java
View File

@@ -15,7 +15,7 @@ import javax.annotation.Nonnull;
/**
* A few helpers for working with arguments.
*
* <p>
* This should really be moved into the public API. However, until I have settled on a suitable format, we'll keep it
* where it is used.
*/

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

@@ -16,9 +16,9 @@ import javax.annotation.Nonnull;
/**
* Methods for interacting with blocks using Forge's energy storage system.
*
* <p>
* This works with energy storage blocks, as well as generators and machines which consume energy.
*
* <p>
* :::note
* Due to limitations with Forge's energy API, it is not possible to measure throughput (i.e. RF
* used/generated per tick).

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

@@ -54,10 +54,10 @@ public class FluidMethods implements GenericPeripheral
/**
* Get all "tanks" in this fluid storage.
*
* <p>
* 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.
*
* <p>
* The returned table is sparse, and so empty tanks will be `nil` - it is recommended to loop over using `pairs`
* rather than `ipairs`.
*
@@ -81,7 +81,7 @@ public class FluidMethods implements GenericPeripheral
/**
* Move a fluid from one fluid container to another connected one.
*
* <p>
* 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.
*
@@ -122,7 +122,7 @@ public class FluidMethods implements GenericPeripheral
/**
* Move a fluid from a connected fluid container into this oneone.
*
* <p>
* 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.
*

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

@@ -67,12 +67,12 @@ public class InventoryMethods implements GenericPeripheral
/**
* List all items in this inventory. This returns a table, with an entry for each slot.
*
* <p>
* 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 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.
*
* <p>
* The returned table is sparse, and so empty slots will be `nil` - it is recommended to loop over using `pairs`
* rather than `ipairs`.
*
@@ -104,13 +104,13 @@ public class InventoryMethods implements GenericPeripheral
/**
* Get detailed information about an item.
*
* <p>
* The returned information contains the same information as each item in
* {@link #list}, as well as additional details like the display name
* (`displayName`), item groups (`itemGroups`), which are the creative tabs
* an item will appear under, and item and item durability (`damage`,
* `maxDamage`, `durability`).
*
* <p>
* 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.
@@ -151,7 +151,7 @@ public class InventoryMethods implements GenericPeripheral
/**
* Get the maximum number of items which can be stored in this slot.
*
* <p>
* Typically this will be limited to 64 items. However, some inventories (such as barrels or caches) can store
* hundreds or thousands of items in one slot.
*
@@ -178,7 +178,7 @@ public class InventoryMethods implements GenericPeripheral
/**
* Push items from one inventory to another connected one.
*
* <p>
* 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.
*
@@ -225,7 +225,7 @@ public class InventoryMethods implements GenericPeripheral
/**
* Pull items from a connected inventory into this one.
*
* <p>
* 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.
*

18
src/main/java/dan200/computercraft/shared/peripheral/modem/ModemPeripheral.java
View File

@@ -22,31 +22,31 @@ import java.util.Set;
/**
* Modems allow you to send messages between computers over long distances.
*
* <p>
* :::tip
* Modems provide a fairly basic set of methods, which makes them very flexible but often hard to work with. The
* {@literal @}{rednet} API is built on top of modems, and provides a more user-friendly interface.
* :::
*
* <p>
* ## Sending and receiving messages
* Modems operate on a series of channels, a bit like frequencies on a radio. Any modem can send a message on a
* particular channel, but only those which have {@link #open opened} the channel and are "listening in" can receive
* messages.
*
* <p>
* Channels are represented as an integer between 0 and 65535 inclusive. These channels don't have any defined meaning,
* though some APIs or programs will assign a meaning to them. For instance, the @{gps} module sends all its messages on
* channel 65534 (@{gps.CHANNEL_GPS}), while @{rednet} uses channels equal to the computer's ID.
*
* <p>
* - Sending messages is done with the {@link #transmit(int, int, Object)} message.
* - Receiving messages is done by listening to the @{modem_message} event.
*
* <p>
* ## Types of modem
* CC: Tweaked comes with three kinds of modem, with different capabilities.
*
* <ul>
* <li><strong>Wireless modems:</strong> Wireless modems can send messages to any other wireless modem. They can be placed next to a
* computer, or equipped as a pocket computer or turtle upgrade.
*
* <p>
* Wireless modems have a limited range, only sending messages to modems within 64 blocks. This range increases
* linearly once the modem is above y=96, to a maximum of 384 at world height.</li>
* <li><strong>Ender modems:</strong> These are upgraded versions of normal wireless modems. They do not have a distance
@@ -75,7 +75,7 @@ import java.util.Set;
*
* print("Received a reply: " .. tostring(message))
* }</pre>
*
* <p>
* ## Recipes
* <div class="recipe-container">
* <mc-recipe recipe="computercraft:wireless_modem_normal"></mc-recipe>
@@ -216,7 +216,7 @@ public abstract class ModemPeripheral implements IPeripheral, IPacketSender, IPa
/**
* Sends a modem message on a certain channel. Modems listening on the channel will queue a {@code modem_message}
* event on adjacent computers.
*
* <p>
* :::note
* The channel does not need be open to send a message.
* :::
@@ -260,7 +260,7 @@ public abstract class ModemPeripheral implements IPeripheral, IPacketSender, IPa
/**
* Determine if this is a wired or wireless modem.
*
* <p>
* Some methods (namely those dealing with wired networks and remote peripherals) are only available on wired
* modems.
*

2
src/main/java/dan200/computercraft/shared/peripheral/modem/wired/WiredModemLocalPeripheral.java
View File

@@ -24,7 +24,7 @@ import java.util.Map;
/**
* Represents a local peripheral exposed on the wired network.
*
* <p>
* This is responsible for getting the peripheral in world, tracking id and type and determining whether
* it has changed.
*/

16
src/main/java/dan200/computercraft/shared/peripheral/modem/wired/WiredModemPeripheral.java
View File

@@ -76,10 +76,10 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements IW
/**
* List all remote peripherals on the wired network.
*
* <p>
* If this computer is attached to the network, it _will not_ be included in
* this list.
*
* <p>
* :::note
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
* :::
@@ -95,7 +95,7 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements IW
/**
* Determine if a peripheral is available on this wired network.
*
* <p>
* :::note
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
* :::
@@ -113,7 +113,7 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements IW
/**
* Get the type of a peripheral is available on this wired network.
*
* <p>
* :::note
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
* :::
@@ -134,7 +134,7 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements IW
/**
* Check a peripheral is of a particular type.
*
* <p>
* :::note
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
* :::
@@ -156,7 +156,7 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements IW
/**
* Get all available methods for the remote peripheral with the given name.
*
* <p>
* :::note
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
* :::
@@ -178,7 +178,7 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements IW
/**
* Call a method on a peripheral on this wired network.
*
* <p>
* :::note
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
* :::
@@ -209,7 +209,7 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements IW
* Returns the network name of the current computer, if the modem is on. This
* may be used by other computers on the network to wrap this computer as a
* peripheral.
*
* <p>
* :::note
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
* :::

6
src/main/java/dan200/computercraft/shared/peripheral/monitor/MonitorPeripheral.java
View File

@@ -19,12 +19,12 @@ import javax.annotation.Nullable;
/**
* Monitors are a block which act as a terminal, displaying information on one side. This allows them to be read and
* interacted with in-world without opening a GUI.
*
* <p>
* Monitors act as @{term.Redirect|terminal redirects} and so expose the same methods, as well as several additional
* ones, which are documented below.
*
* <p>
* Like computers, monitors come in both normal (no colour) and advanced (colour) varieties.
*
* <p>
* ## Recipes
* <div class="recipe-container">
* <mc-recipe recipe="computercraft:monitor_normal"></mc-recipe>

2
src/main/java/dan200/computercraft/shared/peripheral/printer/PrinterPeripheral.java
View File

@@ -17,7 +17,7 @@ import java.util.Optional;
/**
* The printer peripheral allows pages and books to be printed.
*
* <p>
* ## Recipe
* <div class="recipe-container">
* <mc-recipe recipe="computercraft:printer"></mc-recipe>

26
src/main/java/dan200/computercraft/shared/peripheral/speaker/SpeakerPeripheral.java
View File

@@ -35,12 +35,12 @@ import static dan200.computercraft.api.lua.LuaValues.checkFinite;
/**
* The speaker peirpheral allow your computer to play notes and other sounds.
*
* <p>
* The speaker can play three kinds of sound, in increasing orders of complexity:
* - {@link #playNote} allows you to play noteblock note.
* - {@link #playSound} plays any built-in Minecraft sound, such as block sounds or mob noises.
* - {@link #playAudio} can play arbitrary audio.
*
* <p>
* ## Recipe
* <div class="recipe-container">
* <mc-recipe recipe="computercraft:speaker"></mc-recipe>
@@ -193,21 +193,21 @@ public abstract class SpeakerPeripheral implements IPeripheral
/**
* Plays a note block note through the speaker.
*
* <p>
* This takes the name of a note to play, as well as optionally the volume
* and pitch to play the note at.
*
* <p>
* The pitch argument uses semitones as the unit. This directly maps to the
* number of clicks on a note block. For reference, 0, 12, and 24 map to F#,
* and 6 and 18 map to C.
*
* <p>
* A maximum of 8 notes can be played in a single tick. If this limit is hit, this function will return
* {@literal false}.
*
* <p>
* ### Valid instruments
* The speaker supports [all of Minecraft's noteblock instruments](https://minecraft.fandom.com/wiki/Note_Block#Instruments).
* These are:
*
* <p>
* {@code "harp"}, {@code "basedrum"}, {@code "snare"}, {@code "hat"}, {@code "bass"}, @code "flute"},
* {@code "bell"}, {@code "guitar"}, {@code "chime"}, {@code "xylophone"}, {@code "iron_xylophone"},
* {@code "cow_bell"}, {@code "didgeridoo"}, {@code "bit"}, {@code "banjo"} and {@code "pling"}.
@@ -248,10 +248,10 @@ public abstract class SpeakerPeripheral implements IPeripheral
/**
* Plays a Minecraft sound through the speaker.
*
* <p>
* This takes the [name of a Minecraft sound](https://minecraft.fandom.com/wiki/Sounds.json), such as
* {@code "minecraft:block.note_block.harp"}, as well as an optional volume and pitch.
*
* <p>
* Only one sound can be played at once. This function will return {@literal false} if another sound was started
* this tick, or if some {@link #playAudio audio} is still playing.
*
@@ -295,18 +295,18 @@ public abstract class SpeakerPeripheral implements IPeripheral
/**
* Attempt to stream some audio data to the speaker.
*
* <p>
* This accepts a list of audio samples as amplitudes between -128 and 127. These are stored in an internal buffer
* and played back at 48kHz. If this buffer is full, this function will return {@literal false}. You should wait for
* a @{speaker_audio_empty} event before trying again.
*
* <p>
* :::note
* The speaker only buffers a single call to {@link #playAudio} at once. This means if you try to play a small
* number of samples, you'll have a lot of stutter. You should try to play as many samples in one call as possible
* (up to 128×1024), as this reduces the chances of audio stuttering or halting, especially when the server or
* computer is lagging.
* :::
*
* <p>
* {@literal @}{speaker_audio} provides a more complete guide to using speakers
*
* @param context The Lua context.
@@ -361,7 +361,7 @@ public abstract class SpeakerPeripheral implements IPeripheral
/**
* Stop all audio being played by this speaker.
*
* <p>
* This clears any audio that {@link #playAudio} had queued and stops the latest sound played by {@link #playSound}.
*
* @cc.since 1.100

4
src/main/java/dan200/computercraft/shared/pocket/apis/PocketAPI.java
View File

@@ -21,7 +21,7 @@ import net.minecraftforge.items.wrapper.PlayerMainInvWrapper;
/**
* Control the current pocket computer, adding or removing upgrades.
*
* <p>
* This API is only available on pocket computers. As such, you may use its presence to determine what kind of computer
* you are using:
*
@@ -52,7 +52,7 @@ public class PocketAPI implements ILuaAPI
/**
* Search the player's inventory for another upgrade, replacing the existing one with that item if found.
*
* <p>
* This inventory search starts from the player's currently selected slot, allowing you to prioritise upgrades.
*
* @return The result of equipping.

2
src/main/java/dan200/computercraft/shared/pocket/core/PocketServerComputer.java
View File

@@ -139,7 +139,7 @@ public class PocketServerComputer extends ServerComputer implements IPocketAcces
/**
* Set the upgrade for this pocket computer, also updating the item stack.
*
* <p>
* Note this method is not thread safe - it must be called from the server thread.
*
* @param upgrade The new upgrade to set it to, may be {@code null}.

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

@@ -28,47 +28,47 @@ import java.util.Optional;
/**
* Turtles are a robotic device, which can break and place blocks, attack mobs, and move about the world. They have
* an internal inventory of 16 slots, allowing them to store blocks they have broken or would like to place.
*
* <p>
* ## Movement
* Turtles are capable of moving through the world. As turtles are blocks themselves, they are confined to Minecraft's
* grid, moving a single block at a time.
*
* <p>
* {@literal @}{turtle.forward} and @{turtle.back} move the turtle in the direction it is facing, while @{turtle.up} and
* {@literal @}{turtle.down} move it up and down (as one might expect!). In order to move left or right, you first need
* to turn the turtle using @{turtle.turnLeft}/@{turtle.turnRight} and then move forward or backwards.
*
* <p>
* :::info
* The name "turtle" comes from [Turtle graphics], which originated from the Logo programming language. Here you'd move
* a turtle with various commands like "move 10" and "turn left", much like ComputerCraft's turtles!
* :::
*
* <p>
* Moving a turtle (though not turning it) consumes *fuel*. If a turtle does not have any @{turtle.refuel|fuel}, it
* won't move, and the movement functions will return @{false}. If your turtle isn't going anywhere, the first thing to
* check is if you've fuelled your turtle.
*
* <p>
* :::tip Handling errors
* Many turtle functions can fail in various ways. For instance, a turtle cannot move forward if there's already a block
* there. Instead of erroring, functions which can fail either return @{true} if they succeed, or @{false} and some
* error message if they fail.
*
* <p>
* Unexpected failures can often lead to strange behaviour. It's often a good idea to check the return values of these
* functions, or wrap them in @{assert} (for instance, use `assert(turtle.forward())` rather than `turtle.forward()`),
* so the program doesn't misbehave.
* :::
*
* <p>
* ## Turtle upgrades
* While a normal turtle can move about the world and place blocks, its functionality is limited. Thankfully, turtles
* can be upgraded with *tools* and @{peripheral|peripherals}. Turtles have two upgrade slots, one on the left and right
* sides. Upgrades can be equipped by crafting a turtle with the upgrade, or calling the @{turtle.equipLeft}/@{turtle.equipRight}
* functions.
*
* <p>
* Turtle tools allow you to break blocks (@{turtle.dig}) and attack entities (@{turtle.attack}). Some tools are more
* suitable to a task than others. For instance, a diamond pickaxe can break every block, while a sword does more
* damage. Other tools have more niche use-cases, for instance hoes can til dirt.
*
* <p>
* Peripherals (such as the @{modem|wireless modem} or @{speaker}) can also be equipped as upgrades. These are then
* accessible by accessing the `"left"` or `"right"` peripheral.
*
* <p>
* [Turtle Graphics]: https://en.wikipedia.org/wiki/Turtle_graphics "Turtle graphics"
*
* @cc.module turtle
@@ -177,7 +177,7 @@ public class TurtleAPI implements ILuaAPI
/**
* Attempt to break the block in front of the turtle.
*
* <p>
* This requires a turtle tool capable of breaking the block. Diamond pickaxes
* (mining turtles) can break any vanilla block, but other tools (such as axes)
* are more limited.
@@ -229,7 +229,7 @@ public class TurtleAPI implements ILuaAPI
/**
* Place a block or item into the world in front of the turtle.
*
* <p>
* "Placing" an item allows it to interact with blocks and entities in front of the turtle. For instance, buckets
* can pick up and place down fluids, and wheat can be used to breed cows. However, you cannot use {@link #place} to
* perform arbitrary block interactions, such as clicking buttons or flipping levers.
@@ -337,7 +337,7 @@ public class TurtleAPI implements ILuaAPI
/**
* Change the currently selected slot.
*
* <p>
* The selected slot is determines what slot actions like {@link #drop} or {@link #getItemCount} act on.
*
* @param slot The slot to select.
@@ -373,7 +373,7 @@ public class TurtleAPI implements ILuaAPI
/**
* Get the remaining number of items which may be stored in this stack.
*
* <p>
* For instance, if a slot contains 13 blocks of dirt, it has room for another 51.
*
* @param slot The slot we wish to check. Defaults to the {@link #select selected slot}.
@@ -514,7 +514,7 @@ public class TurtleAPI implements ILuaAPI
/**
* Suck an item from the inventory in front of the turtle, or from an item floating in the world.
*
* <p>
* This will pull items into the first acceptable slot, starting at the {@link #select currently selected} one.
*
* @param count The number of items to suck. If not given, up to a stack of items will be picked up.
@@ -583,10 +583,10 @@ public class TurtleAPI implements ILuaAPI
/**
* Refuel this turtle.
*
* <p>
* While most actions a turtle can perform (such as digging or placing blocks) are free, moving consumes fuel from
* the turtle's internal buffer. If a turtle has no fuel, it will not move.
*
* <p>
* {@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.
@@ -675,7 +675,7 @@ public class TurtleAPI implements ILuaAPI
/**
* Get the maximum amount of fuel this turtle can hold.
*
* <p>
* By default, normal turtles have a limit of 20,000 and advanced turtles of 100,000.
*
* @return The limit, or "unlimited".
@@ -693,7 +693,7 @@ public class TurtleAPI implements ILuaAPI
/**
* Equip (or unequip) an item on the left side of this turtle.
*
* <p>
* 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.
@@ -713,7 +713,7 @@ public class TurtleAPI implements ILuaAPI
/**
* Equip (or unequip) an item on the right side of this turtle.
*
* <p>
* 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.

2
src/main/java/dan200/computercraft/shared/util/InventoryDelegate.java
View File

@@ -15,7 +15,7 @@ import java.util.Set;
/**
* Provides a delegate over inventories.
*
* <p>
* This may be used both on {@link net.minecraft.tileentity.TileEntity}s to redirect the inventory to another tile,
* and by other interfaces to have inventories which change their backing store.
*/

4
src/main/java/dan200/computercraft/shared/util/ThreadUtils.java
View File

@@ -44,7 +44,7 @@ public final class ThreadUtils
/**
* Create a new {@link ThreadFactoryBuilder}, which constructs threads under a group of the given {@code name}.
*
* <p>
* Each thread will be of the format {@code ComputerCraft-<name>-<number>}, and belong to a group
* called {@code ComputerCraft-<name>} (which in turn will be a child group of the main {@code ComputerCraft} group.
*
@@ -64,7 +64,7 @@ public final class ThreadUtils
/**
* Create a new {@link ThreadFactory}, which constructs threads under a group of the given {@code name}.
*
* <p>
* Each thread will be of the format {@code ComputerCraft-<name>-<number>}, and belong to a group
* called {@code ComputerCraft-<name>} (which in turn will be a child group of the main {@code ComputerCraft} group.
*

2
src/main/java/dan200/computercraft/shared/util/TickScheduler.java
View File

@@ -19,7 +19,7 @@ import java.util.concurrent.ConcurrentLinkedDeque;
/**
* A thread-safe version of {@link ITickList#scheduleTick(BlockPos, Object, int)}.
*
* <p>
* We use this when modems and other peripherals change a block in a different thread.
*/
@Mod.EventBusSubscriber( modid = ComputerCraft.MOD_ID )

2
src/main/java/dan200/computercraft/shared/util/WaterloggableHelpers.java
View File

@@ -17,7 +17,7 @@ import net.minecraft.world.IWorld;
/**
* Represents a block which can be filled with water
*
* <p>
* I'm fairly sure this exists on 1.14, but it's a useful convenience wrapper to have on 1.13.
*/
public final class WaterloggableHelpers

Some files were not shown because too many files have changed in this diff Show More