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

Rewrite several doc introductions

Browse Source 
Mostly focussing on rednet and modem here. Not sure if I made them any
better, we'll see!
This commit is contained in:
Jonathan Coates
2021-12-21 00:22:16 +00:00
parent 5eedea1bbb
commit 932b77d7ee
10 changed files with 276 additions and 136 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -19,10 +19,10 @@ import javax.annotation.Nonnull;
*
* This works with energy storage blocks, as well as generators and machines which consume energy.
*
* <blockquote>
* <strong>Note:</strong> Due to limitations with Forge's energy API, it is not possible to measure throughput (i.e. RF
* :::note
* Due to limitations with Forge's energy API, it is not possible to measure throughput (i.e. RF
* used/generated per tick).
* </blockquote>
* :::
*
* @cc.module energy_storage
*/

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

@@ -21,9 +21,60 @@ import java.util.HashSet;
import java.util.Set;
/**
* The modem peripheral allows you to send messages between computers.
* Modems allow you to send messages between computers over long distances.
*
* :::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.
* :::
*
* ## 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.
*
* 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.
*
* - Sending messages is done with the {@link #transmit(int, int, Object)} message.
* - Receiving messages is done by listening to the @{modem_message} event.
*
* ## 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.
*
* 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
* limit, and can send messages between dimensions.</li>
* <li><strong>Wired modems:</strong> These send messages to other any other wired modems connected to the same network
* (using <em>Networking Cable</em>). They also can be used to attach additional peripherals to a computer.</li></ul>
*
* @cc.module modem
* @cc.see modem_message Queued when a modem receives a message on an {@link #open(int) open channel}.
* @cc.see rednet A networking API built on top of the modem peripheral.
* @cc.usage Wrap a modem and a message on channel 15, requesting a response on channel 43. Then wait for a message to
* arrive on channel 43 and print it.
*
* <pre>{@code
* local modem = peripheral.find("modem") or error("No modem attached", 0)
* modem.open(43) -- Open 43 so we can receive replies
*
* -- Send our message
* modem.transmit(15, 43, "Hello, world!")
*
* -- And wait for a reply
* local event, side, channel, replyChannel, message, distance
* repeat
* event, side, channel, replyChannel, message, distance = os.pullEvent("modem_message")
* until channel == 43
*
* print("Received a reply: " .. tostring(message))
* }</pre>
*/
public abstract class ModemPeripheral implements IPeripheral, IPacketSender, IPacketReceiver
{
@@ -157,12 +208,23 @@ 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.
*
* <blockquote><strong>Note:</strong> The channel does not need be open to send a message.</blockquote>
* :::note
* The channel does not need be open to send a message.
* :::
*
* @param channel The channel to send messages on.
* @param replyChannel The channel that responses to this message should be sent on.
* @param payload The object to send. This can be a boolean, string, number, or table.
* @param replyChannel The channel that responses to this message should be sent on. This can be the same as
* {@code channel} or entirely different. The channel must have been {@link #open opened} on
* the sending computer in order to receive the replies.
* @param payload The object to send. This can be any primitive type (boolean, number, string) as well as
* tables. Other types (like functions), as well as metatables, will not be transmitted.
* @throws LuaException If the channel is out of range.
* @cc.usage Wrap a modem and a message on channel 15, requesting a response on channel 43.
*
* <pre>{@code
* local modem = peripheral.find("modem") or error("No modem attached", 0)
* modem.transmit(15, 43, "Hello, world!")
* }</pre>
*/
@LuaFunction
public final void transmit( int channel, int replyChannel, Object payload ) throws LuaException

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

@@ -80,8 +80,9 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements IW
* If this computer is attached to the network, it _will not_ be included in
* this list.
*
* <blockquote><strong>Important:</strong> This function only appears on wired modems. Check {@link #isWireless}
* returns false before calling it.</blockquote>
* :::note
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
* :::
*
* @param computer The calling computer.
* @return Remote peripheral names on the network.
@@ -95,8 +96,9 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements IW
/**
* Determine if a peripheral is available on this wired network.
*
* <blockquote><strong>Important:</strong> This function only appears on wired modems. Check {@link #isWireless}
* returns false before calling it.</blockquote>
* :::note
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
* :::
*
* @param computer The calling computer.
* @param name The peripheral's name.
@@ -112,8 +114,9 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements IW
/**
* Get the type of a peripheral is available on this wired network.
*
* <blockquote><strong>Important:</strong> This function only appears on wired modems. Check {@link #isWireless}
* returns false before calling it.</blockquote>
* :::note
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
* :::
*
* @param computer The calling computer.
* @param name The peripheral's name.
@@ -132,8 +135,9 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements IW
/**
* Check a peripheral is of a particular type.
*
* <blockquote><strong>Important:</strong> This function only appears on wired modems. Check {@link #isWireless}
* returns false before calling it.</blockquote>
* :::note
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
* :::
*
* @param computer The calling computer.
* @param name The peripheral's name.
@@ -153,8 +157,9 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements IW
/**
* Get all available methods for the remote peripheral with the given name.
*
* <blockquote><strong>Important:</strong> This function only appears on wired modems. Check {@link #isWireless}
* returns false before calling it.</blockquote>
* :::note
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
* :::
*
* @param computer The calling computer.
* @param name The peripheral's name.
@@ -174,8 +179,9 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements IW
/**
* Call a method on a peripheral on this wired network.
*
* <blockquote><strong>Important:</strong> This function only appears on wired modems. Check {@link #isWireless}
* returns false before calling it.</blockquote>
* :::note
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
* :::
*
* @param computer The calling computer.
* @param context The Lua context we're executing in.
@@ -204,8 +210,9 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements IW
* may be used by other computers on the network to wrap this computer as a
* peripheral.
*
* <blockquote><strong>Important:</strong> This function only appears on wired modems. Check {@link #isWireless}
* returns false before calling it.</blockquote>
* :::note
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
* :::
*
* @return The current computer's name.
* @cc.treturn string|nil The current computer's name on the wired network.