From 2055052a57037ccf7029d506b5437cce2925d46b Mon Sep 17 00:00:00 2001 From: Jonathan Coates Date: Wed, 23 Aug 2023 18:10:01 +0100 Subject: [PATCH] Switch to GitHub-style admonitions/alerts As these are just a custom syntax on top of blockquotes, these work much better with text editors. --- doc/guides/gps_setup.md | 39 +++++++++---------- doc/guides/speaker_audio.md | 7 ++-- doc/stub/global.lua | 22 +++++------ illuaminate.sexp | 2 +- .../peripheral/modem/ModemPeripheral.java | 12 +++--- .../modem/wired/WiredModemPeripheral.java | 35 +++++++---------- .../peripheral/speaker/SpeakerPeripheral.java | 11 +++--- .../shared/turtle/apis/TurtleAPI.java | 24 ++++++------ .../dan200/computercraft/core/apis/FSAPI.java | 7 ++-- .../dan200/computercraft/core/apis/OSAPI.java | 13 +++---- .../lua/rom/apis/command/commands.lua | 7 ++-- .../data/computercraft/lua/rom/apis/disk.lua | 7 ++-- .../data/computercraft/lua/rom/apis/gps.lua | 9 ++--- .../computercraft/lua/rom/apis/parallel.lua | 36 ++++++++--------- .../computercraft/lua/rom/apis/peripheral.lua | 9 ++--- .../computercraft/lua/rom/apis/rednet.lua | 17 ++++---- .../computercraft/lua/rom/apis/settings.lua | 14 +++---- .../lua/rom/modules/main/cc/audio/dfpwm.lua | 14 +++---- .../main/cc/internal/error_printer.lua | 7 ++-- .../modules/main/cc/internal/exception.lua | 7 ++-- .../rom/modules/main/cc/internal/import.lua | 7 ++-- .../main/cc/internal/syntax/errors.lua | 7 ++-- .../modules/main/cc/internal/syntax/init.lua | 7 ++-- .../modules/main/cc/internal/syntax/lexer.lua | 7 ++-- .../main/cc/internal/syntax/parser.lua | 7 ++-- .../generic/methods/EnergyMethods.java | 7 ++-- .../generic/methods/InventoryMethods.java | 11 +++--- 27 files changed, 156 insertions(+), 196 deletions(-) diff --git a/doc/guides/gps_setup.md b/doc/guides/gps_setup.md index 7aab005d0..6d57a5880 100644 --- a/doc/guides/gps_setup.md +++ b/doc/guides/gps_setup.md @@ -25,16 +25,15 @@ ## Building a GPS constellation modems or 4 ender modems. Try not to mix ender and wireless modems together as you might get some odd behavior when your requesting computers are out of range. -:::tip Ender modems vs wireless modems -Ender modems have a very large range, which makes them very useful for setting up GPS hosts. If you do this then you -will likely only need one GPS constellation for the whole dimension (such as the Overworld or Nether). - -If you do use wireless modems then you may find that you need multiple GPS constellations to cover your needs. - -A computer needs a wireless or ender modem and to be in range of a GPS constellation that is in the same dimension as it -to use the GPS API. The reason for this is that ComputerCraft mimics real-life GPS by making use of the distance -parameter of @{modem_message|modem messages} and some maths. -::: +> [Ender modems vs wireless modems][!TIP] +> Ender modems have a very large range, which makes them very useful for setting up GPS hosts. If you do this then you +> will likely only need one GPS constellation for the whole dimension (such as the Overworld or Nether). +> +> If you do use wireless modems then you may find that you need multiple GPS constellations to cover your needs. +> +> A computer needs a wireless or ender modem and to be in range of a GPS constellation that is in the same dimension as +> it to use the GPS API. The reason for this is that ComputerCraft mimics real-life GPS by making use of the distance +> parameter of @{modem_message|modem messages} and some maths. Locate where you want to place your GPS constellation. You will need an area at least 6 blocks high, 6 blocks wide, and 6 blocks deep (6x6x6). If you are using wireless modems then you may want to build your constellation as high as you can @@ -79,18 +78,16 @@ ## Configuring the constellation Create similar startup files for the other computers in your constellation, making sure to input the each computer's own coordinates. -:::caution Modem messages come from the computer's position, not the modem's -Wireless modems transmit from the block that they are attached to *not* the block space that they occupy, the -coordinates that you input into your GPS host should be the position of the computer and not the position of the modem. -::: +> [Modem messages come from the computer's position, not the modem's][!WARNING] +> Wireless modems transmit from the block that they are attached to *not* the block space that they occupy, the +> coordinates that you input into your GPS host should be the position of the computer and not the position of the modem. Congratulations, your constellation is now fully set up! You can test it by placing another computer close by, placing a wireless modem on it, and running the `gps locate` program (or calling the @{gps.locate} function). -:::info Why use Minecraft's coordinates? -CC doesn't care if you use Minecraft's coordinate system, so long as all of the GPS hosts with overlapping ranges use -the same reference point (requesting computers will get confused if hosts have different reference points). However, -using MC's coordinate system does provide a nice standard to adopt server-wide. It also is consistent with how command -computers get their location, they use MC's command system to get their block which returns that in MC's coordinate -system. -::: +> [Why use Minecraft's coordinates?][!INFO] +> CC doesn't care if you use Minecraft's coordinate system, so long as all of the GPS hosts with overlapping ranges use +> the same reference point (requesting computers will get confused if hosts have different reference points). However, +> using MC's coordinate system does provide a nice standard to adopt server-wide. It also is consistent with how command +> computers get their location, they use MC's command system to get their block which returns that in MC's coordinate +> system. diff --git a/doc/guides/speaker_audio.md b/doc/guides/speaker_audio.md index 1ced4fff1..f498c2d70 100644 --- a/doc/guides/speaker_audio.md +++ b/doc/guides/speaker_audio.md @@ -189,10 +189,9 @@ ## Processing audio end ``` -:::note Confused? -Don't worry if you don't understand this example. It's quite advanced, and does use some ideas that this guide doesn't -cover. That said, don't be afraid to ask on [GitHub Discussions] or [IRC] either! -::: +> [Confused?][!NOTE] +> Don't worry if you don't understand this example. It's quite advanced, and does use some ideas that this guide doesn't +> cover. That said, don't be afraid to ask on [GitHub Discussions] or [IRC] either! It's worth noting that the examples of audio processing we've mentioned here are about manipulating the _amplitude_ of the wave. If you wanted to modify the _frequency_ (for instance, shifting the pitch), things get rather more complex. diff --git a/doc/stub/global.lua b/doc/stub/global.lua index 1065c1497..e8474f803 100644 --- a/doc/stub/global.lua +++ b/doc/stub/global.lua @@ -16,19 +16,17 @@ rounded up to the nearest multiple of 0.05 seconds. If you are using coroutines or the @{parallel|parallel API}, it will only pause execution of the current thread, not the whole program. -:::tip -Because sleep internally uses timers, it is a function that yields. This means -that you can use it to prevent "Too long without yielding" errors. However, as -the minimum sleep time is 0.05 seconds, it will slow your program down. -::: +> [!TIP] +> Because sleep internally uses timers, it is a function that yields. This means +> that you can use it to prevent "Too long without yielding" errors. However, as +> the minimum sleep time is 0.05 seconds, it will slow your program down. -:::caution -Internally, this function queues and waits for a timer event (using -@{os.startTimer}), however it does not listen for any other events. This means -that any event that occurs while sleeping will be entirely discarded. If you -need to receive events while sleeping, consider using @{os.startTimer|timers}, -or the @{parallel|parallel API}. -::: +> [!WARNING] +> Internally, this function queues and waits for a timer event (using +> @{os.startTimer}), however it does not listen for any other events. This means +> that any event that occurs while sleeping will be entirely discarded. If you +> need to receive events while sleeping, consider using @{os.startTimer|timers}, +> or the @{parallel|parallel API}. @tparam number time The number of seconds to sleep for, rounded up to the nearest multiple of 0.05. diff --git a/illuaminate.sexp b/illuaminate.sexp index 74b37f146..db2aa3a12 100644 --- a/illuaminate.sexp +++ b/illuaminate.sexp @@ -12,7 +12,6 @@ /projects/core/src/test/resources/test-rom /projects/web/src/mount) - (doc ; Also defined in projects/web/build.gradle.kts (destination /projects/web/build/illuaminate) @@ -50,6 +49,7 @@ (at / (linters syntax:string-index + doc:docusaurus-admonition ;; It'd be nice to avoid this, but right now there's a lot of instances of ;; it. diff --git a/projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/ModemPeripheral.java b/projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/ModemPeripheral.java index 7b1cf5dfa..672e016f3 100644 --- a/projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/ModemPeripheral.java +++ b/projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/ModemPeripheral.java @@ -21,10 +21,9 @@ /** * 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. - * ::: + * > [!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 @@ -198,9 +197,8 @@ public final void closeAll() { * Sends a modem message on a certain channel. Modems listening on the channel will queue a {@code modem_message} * event on adjacent computers. *

- * :::note - * The channel does not need be open to send a message. - * ::: + * > [!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. This can be the same as diff --git a/projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/wired/WiredModemPeripheral.java b/projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/wired/WiredModemPeripheral.java index a4956ac69..8e0a6f8bb 100644 --- a/projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/wired/WiredModemPeripheral.java +++ b/projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/wired/WiredModemPeripheral.java @@ -80,9 +80,8 @@ public Set getAdditionalTypes() { * If this computer is attached to the network, it _will not_ be included in * this list. *

- * :::note - * This function only appears on wired modems. Check {@link #isWireless} returns false before calling it. - * ::: + * > [!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. @@ -96,9 +95,8 @@ public final Collection getNamesRemote(IComputerAccess computer) { /** * Determine if a peripheral is available on this wired network. *

- * :::note - * This function only appears on wired modems. Check {@link #isWireless} returns false before calling it. - * ::: + * > [!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. @@ -113,9 +111,8 @@ public final boolean isPresentRemote(IComputerAccess computer, String name) { /** * Get the type of a peripheral is available on this wired network. *

- * :::note - * This function only appears on wired modems. Check {@link #isWireless} returns false before calling it. - * ::: + * > [!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. @@ -133,9 +130,8 @@ public final boolean isPresentRemote(IComputerAccess computer, String name) { /** * Check a peripheral is of a particular type. *

- * :::note - * This function only appears on wired modems. Check {@link #isWireless} returns false before calling it. - * ::: + * > [!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. @@ -154,9 +150,8 @@ public final boolean isPresentRemote(IComputerAccess computer, String name) { /** * Get all available methods for the remote peripheral with the given name. *

- * :::note - * This function only appears on wired modems. Check {@link #isWireless} returns false before calling it. - * ::: + * > [!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. @@ -175,9 +170,8 @@ public final boolean isPresentRemote(IComputerAccess computer, String name) { /** * Call a method on a peripheral on this wired network. *

- * :::note - * This function only appears on wired modems. Check {@link #isWireless} returns false before calling it. - * ::: + * > [!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. @@ -205,9 +199,8 @@ public final MethodResult callRemote(IComputerAccess computer, ILuaContext conte * may be used by other computers on the network to wrap this computer as a * peripheral. *

- * :::note - * This function only appears on wired modems. Check {@link #isWireless} returns false before calling it. - * ::: + * > [!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. diff --git a/projects/common/src/main/java/dan200/computercraft/shared/peripheral/speaker/SpeakerPeripheral.java b/projects/common/src/main/java/dan200/computercraft/shared/peripheral/speaker/SpeakerPeripheral.java index 4a6ab7ef0..75d3cc2fe 100644 --- a/projects/common/src/main/java/dan200/computercraft/shared/peripheral/speaker/SpeakerPeripheral.java +++ b/projects/common/src/main/java/dan200/computercraft/shared/peripheral/speaker/SpeakerPeripheral.java @@ -274,12 +274,11 @@ public final boolean playSound(ILuaContext context, String name, Optional - * :::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. - * ::: + * > [!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. *

* {@literal @}{speaker_audio} provides a more complete guide to using speakers * diff --git a/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java b/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java index feb4ffc6d..7a50bf5e2 100644 --- a/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java +++ b/projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java @@ -27,24 +27,22 @@ * {@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. *

- * :::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! - * ::: + * > [!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! *

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

- * :::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. - *

- * 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. - * ::: + * > [Handling errors][!TIP] + * > 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. + * > + * > 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. *

* ## Turtle upgrades * While a normal turtle can move about the world and place blocks, its functionality is limited. Thankfully, turtles diff --git a/projects/core/src/main/java/dan200/computercraft/core/apis/FSAPI.java b/projects/core/src/main/java/dan200/computercraft/core/apis/FSAPI.java index c300bd0df..7235a4382 100644 --- a/projects/core/src/main/java/dan200/computercraft/core/apis/FSAPI.java +++ b/projects/core/src/main/java/dan200/computercraft/core/apis/FSAPI.java @@ -37,10 +37,9 @@ * {@link #copy} and {@link #delete}. * *

- * :::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. - * ::: + * > [!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. *

* ## Mounts * While a computer can only have one hard drive and filesystem, other filesystems may be "mounted" inside it. For diff --git a/projects/core/src/main/java/dan200/computercraft/core/apis/OSAPI.java b/projects/core/src/main/java/dan200/computercraft/core/apis/OSAPI.java index 86b395e9b..84206b527 100644 --- a/projects/core/src/main/java/dan200/computercraft/core/apis/OSAPI.java +++ b/projects/core/src/main/java/dan200/computercraft/core/apis/OSAPI.java @@ -353,13 +353,12 @@ public final int day(Optional args) throws LuaException { * * If called with {@code local}, returns the number of milliseconds since 1 * January 1970 in the server's local timezone. *

- * :::info - * The {@code ingame} time zone assumes that one Minecraft day consists of 86,400,000 - * milliseconds. Since one in-game day is much faster than a real day (20 minutes), this - * will change quicker than real time - one real second is equal to 72000 in-game - * milliseconds. If you wish to convert this value to real time, divide by 72000; to - * convert to ticks (where a day is 24000 ticks), divide by 3600. - * ::: + * > [!INFO] + * > The {@code ingame} time zone assumes that one Minecraft day consists of 86,400,000 + * > milliseconds. Since one in-game day is much faster than a real day (20 minutes), this + * > will change quicker than real time - one real second is equal to 72000 in-game + * > milliseconds. If you wish to convert this value to real time, divide by 72000; to + * > convert to ticks (where a day is 24000 ticks), divide by 3600. * * @param args The locale to get the milliseconds for. Defaults to {@code ingame} if not set. * @return The milliseconds since the epoch depending on the selected locale. diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/command/commands.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/command/commands.lua index 315e17358..db947193a 100644 --- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/command/commands.lua +++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/command/commands.lua @@ -5,10 +5,9 @@ --[[- Execute [Minecraft commands][mc] and gather data from the results from a command computer. -:::note -This API is only available on Command computers. It is not accessible to normal -players. -::: +> [!NOTE] +> This API is only available on Command computers. It is not accessible to normal +> players. While one may use @{commands.exec} directly to execute a command, the commands API also provides helper methods to execute every command. For diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/disk.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/disk.lua index cf518bfba..62f6f923f 100644 --- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/disk.lua +++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/disk.lua @@ -9,10 +9,9 @@ locally attached drive, specify “side” as one of the six sides (e.g. `left`) use a remote disk drive, specify its name as printed when enabling its modem (e.g. `drive_0`). -:::tip -All computers (except command computers), turtles and pocket computers can be -placed within a disk drive to access it's internal storage like a disk. -::: +> [!TIP] +> All computers (except command computers), turtles and pocket computers can be +> placed within a disk drive to access it's internal storage like a disk. @module disk @since 1.2 diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/gps.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/gps.lua index d95715fe0..d4a49a5d7 100644 --- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/gps.lua +++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/gps.lua @@ -12,11 +12,10 @@ and the fourth should be either above or below the other three. The three in a plane should not be in a line with each other. You can set up hosts using the gps program. -:::note -When entering in the coordinates for the host you need to put in the `x`, `y`, -and `z` coordinates of the block that the modem is connected to, not the modem. -All modem distances are measured from the block that the modem is placed on. -::: +> [!NOTE] +> When entering in the coordinates for the host you need to put in the `x`, `y`, +> and `z` coordinates of the block that the modem is connected to, not the modem. +> All modem distances are measured from the block that the modem is placed on. Also note that you may choose which axes x, y, or z refers to - so long as your systems have the same definition as any GPS servers that're in range, it works diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/parallel.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/parallel.lua index 20b2b1e8f..379655595 100644 --- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/parallel.lua +++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/parallel.lua @@ -17,25 +17,23 @@ etc) can safely be used in one without affecting the event queue accessed by the other. -:::caution -When using this API, be careful to pass the functions you want to run in -parallel, and _not_ the result of calling those functions. - -For instance, the following is correct: - -```lua -local function do_sleep() sleep(1) end -parallel.waitForAny(do_sleep, rednet.receive) -``` - -but the following is **NOT**: - -```lua -local function do_sleep() sleep(1) end -parallel.waitForAny(do_sleep(), rednet.receive) -``` - -::: +> [!WARNING] +> When using this API, be careful to pass the functions you want to run in +> parallel, and _not_ the result of calling those functions. +> +> For instance, the following is correct: +> +> ```lua +> local function do_sleep() sleep(1) end +> parallel.waitForAny(do_sleep, rednet.receive) +> ``` +> +> but the following is **NOT**: +> +> ```lua +> local function do_sleep() sleep(1) end +> parallel.waitForAny(do_sleep(), rednet.receive) +> ``` @module parallel @since 1.2 diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua index a7a291d7e..19d0626ef 100644 --- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua +++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua @@ -35,11 +35,10 @@ Once you have the name of a peripheral, you can call functions on it using the @{peripheral.call} function. This takes the name of our peripheral, the name of the function we want to call, and then its arguments. -:::info -Some bits of the peripheral API call peripheral functions *methods* instead -(for example, the @{peripheral.getMethods} function). Don't worry, they're the -same thing! -::: +> [!INFO] +> Some bits of the peripheral API call peripheral functions *methods* instead +> (for example, the @{peripheral.getMethods} function). Don't worry, they're the +> same thing! Let's say we have a monitor above our computer (and so "top") and want to @{monitor.write|write some text to it}. We'd write the following: diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/rednet.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/rednet.lua index a2d168cc0..9acf4c650 100644 --- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/rednet.lua +++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/rednet.lua @@ -16,15 +16,14 @@ Once rednet is opened, you can send messages using @{rednet.send} and receive them using @{rednet.receive}. It's also possible to send a message to _every_ rednet-using computer using @{rednet.broadcast}. -:::caution Network security - -While rednet provides a friendly way to send messages to specific computers, it -doesn't provide any guarantees about security. Other computers could be -listening in to your messages, or even pretending to send messages from other computers! - -If you're playing on a multi-player server (or at least one where you don't -trust other players), it's worth encrypting or signing your rednet messages. -::: +> [Network security][!WARNING] +> +> While rednet provides a friendly way to send messages to specific computers, it +> doesn't provide any guarantees about security. Other computers could be +> listening in to your messages, or even pretending to send messages from other computers! +> +> If you're playing on a multi-player server (or at least one where you don't +> trust other players), it's worth encrypting or signing your rednet messages. ## Protocols and hostnames Several rednet messages accept "protocol"s - simple string names describing what diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/settings.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/settings.lua index d1481401b..3ecca4312 100644 --- a/projects/core/src/main/resources/data/computercraft/lua/rom/apis/settings.lua +++ b/projects/core/src/main/resources/data/computercraft/lua/rom/apis/settings.lua @@ -8,10 +8,9 @@ When a computer starts, it reads the current value of settings from the `/.settings` file. These values then may be @{settings.get|read} or @{settings.set|modified}. -:::caution -Calling @{settings.set} does _not_ update the settings file by default. You -_must_ call @{settings.save} to persist values. -::: +> [!WARNING] +> Calling @{settings.set} does _not_ update the settings file by default. You +> _must_ call @{settings.save} to persist values. @module settings @since 1.78 @@ -113,10 +112,9 @@ end --[[- Set the value of a setting. -:::caution -Calling @{settings.set} does _not_ update the settings file by default. You -_must_ call @{settings.save} to persist values. -::: +> [!WARNING] +> Calling @{settings.set} does _not_ update the settings file by default. You +> _must_ call @{settings.save} to persist values. @tparam string name The name of the setting to set @param value The setting's value. This cannot be `nil`, and must be diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/audio/dfpwm.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/audio/dfpwm.lua index fb35af58b..d7b24d480 100644 --- a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/audio/dfpwm.lua +++ b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/audio/dfpwm.lua @@ -95,10 +95,9 @@ end The returned encoder is itself a function. This function accepts a table of amplitude data between -128 and 127 and returns the encoded DFPWM data. -:::caution Reusing encoders -Encoders have lots of internal state which tracks the state of the current stream. If you reuse an encoder for multiple -streams, or use different encoders for the same stream, the resulting audio may not sound correct. -::: +> [Reusing encoders][!WARNING] +> Encoders have lots of internal state which tracks the state of the current stream. If you reuse an encoder for multiple +> streams, or use different encoders for the same stream, the resulting audio may not sound correct. @treturn function(pcm: { number... }):string The encoder function @see encode A helper function for encoding an entire file of audio at once. @@ -138,10 +137,9 @@ end The returned decoder is itself a function. This function accepts a string and returns a table of amplitudes, each value between -128 and 127. -:::caution Reusing decoders -Decoders have lots of internal state which tracks the state of the current stream. If you reuse an decoder for multiple -streams, or use different decoders for the same stream, the resulting audio may not sound correct. -::: +> [Reusing decoders][!WARNING] +> Decoders have lots of internal state which tracks the state of the current stream. If you reuse an decoder for +> multiple streams, or use different decoders for the same stream, the resulting audio may not sound correct. @treturn function(dfpwm: string):{ number... } The encoder function @see decode A helper function for decoding an entire file of audio at once. diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/error_printer.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/error_printer.lua index 6619bee90..b9654a39f 100644 --- a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/error_printer.lua +++ b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/error_printer.lua @@ -4,10 +4,9 @@ --[[- A pretty-printer for Lua errors. -:::warning -This is an internal module and SHOULD NOT be used in your own code. It may -be removed or changed at any time. -::: +> [!DANGER] +> This is an internal module and SHOULD NOT be used in your own code. It may +> be removed or changed at any time. This consumes a list of messages and "annotations" and displays the error to the terminal. diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/exception.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/exception.lua index c2def8c61..64156934f 100644 --- a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/exception.lua +++ b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/exception.lua @@ -4,10 +4,9 @@ --[[- Internal tools for working with errors. -:::warning -This is an internal module and SHOULD NOT be used in your own code. It may -be removed or changed at any time. -::: +> [!DANGER] +> This is an internal module and SHOULD NOT be used in your own code. It may +> be removed or changed at any time. @local ]] diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/import.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/import.lua index 8b03e3c4c..31fd3a93f 100644 --- a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/import.lua +++ b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/import.lua @@ -4,10 +4,9 @@ --[[- Upload a list of files, as received by the @{event!file_transfer} event. -:::warning -This is an internal module and SHOULD NOT be used in your own code. It may -be removed or changed at any time. -::: +> [!DANGER] +> This is an internal module and SHOULD NOT be used in your own code. It may +> be removed or changed at any time. @local ]] diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/errors.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/errors.lua index 2fcf9aa10..c4f2e1cd0 100644 --- a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/errors.lua +++ b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/errors.lua @@ -4,10 +4,9 @@ --[[- The error messages reported by our lexer and parser. -:::warning -This is an internal module and SHOULD NOT be used in your own code. It may -be removed or changed at any time. -::: +> [!DANGER] +> This is an internal module and SHOULD NOT be used in your own code. It may +> be removed or changed at any time. This provides a list of factory methods which take source positions and produce appropriate error messages targeting that location. These error messages can diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/init.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/init.lua index 59125c945..2a69d890f 100644 --- a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/init.lua +++ b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/init.lua @@ -4,10 +4,9 @@ --[[- The main entrypoint to our Lua parser -:::warning -This is an internal module and SHOULD NOT be used in your own code. It may -be removed or changed at any time. -::: +> [!DANGER] +> This is an internal module and SHOULD NOT be used in your own code. It may +> be removed or changed at any time. @local ]] diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/lexer.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/lexer.lua index e775d590b..dbbe39d5a 100644 --- a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/lexer.lua +++ b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/lexer.lua @@ -4,10 +4,9 @@ --[[- A lexer for Lua source code. -:::warning -This is an internal module and SHOULD NOT be used in your own code. It may -be removed or changed at any time. -::: +> [!DANGER] +> This is an internal module and SHOULD NOT be used in your own code. It may +> be removed or changed at any time. This module provides utilities for lexing Lua code, returning tokens compatible with @{cc.internal.syntax.parser}. While all lexers are roughly the same, there diff --git a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/parser.lua b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/parser.lua index 507f03928..4e60da420 100644 --- a/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/parser.lua +++ b/projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/parser.lua @@ -4,10 +4,9 @@ --[[- A parser for Lua programs and expressions. -:::warning -This is an internal module and SHOULD NOT be used in your own code. It may -be removed or changed at any time. -::: +> [!DANGER] +> This is an internal module and SHOULD NOT be used in your own code. It may +> be removed or changed at any time. Most of the code in this module is automatically generated from the Lua grammar, hence being mostly unreadable! diff --git a/projects/forge/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/EnergyMethods.java b/projects/forge/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/EnergyMethods.java index 92565043c..992675cbf 100644 --- a/projects/forge/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/EnergyMethods.java +++ b/projects/forge/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/EnergyMethods.java @@ -15,10 +15,9 @@ *

* This works with energy storage blocks, as well as generators and machines which consume energy. *

- * :::note - * Due to limitations with Forge's energy API, it is not possible to measure throughput (i.e. RF - * used/generated per tick). - * ::: + * > [!NOTE] + * > Due to limitations with Forge's energy API, it is not possible to measure throughput (i.e. RF + * > used/generated per tick). * * @cc.module energy_storage * @cc.since 1.94.0 diff --git a/projects/forge/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/InventoryMethods.java b/projects/forge/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/InventoryMethods.java index 290b8e09f..4ef6aa75e 100644 --- a/projects/forge/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/InventoryMethods.java +++ b/projects/forge/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/InventoryMethods.java @@ -102,12 +102,11 @@ public static int size(IItemHandler inventory) { * recommended to print it out using @{textutils.serialize} or in the Lua * REPL, to explore what is available. *

- * :::info Deprecated fields - * Older versions of CC: Tweaked exposed an {@code itemGroups} field, listing the - * creative tabs an item was available under. This information is no longer available on - * more recent versions of the game, and so this field will always be empty. Do not use this - * field in new code! - * ::: + * > [Deprecated fields][!INFO] + * > Older versions of CC: Tweaked exposed an {@code itemGroups} field, listing the + * > creative tabs an item was available under. This information is no longer available on + * > more recent versions of the game, and so this field will always be empty. Do not use this + * > field in new code! * * @param inventory The current inventory. * @param slot The slot to get information about.