Some minor documentation improvements

- Start making the summary lines for modules a little better. Just say
   what the module does, rather than "The X API does Y" or "Provides Y".
   There's still a lot of work to be done here.

 - Bundle prism.js on the page, so we can highlight non-Lua code.

 - Copy our local_ips wiki page to the main docs.

doc/guides/local_ips.md

@@ -0,0 +1,95 @@
+---
+module: [kind=guide] local_ips
+---
+
+# Allowing access to local IPS
+By default, ComputerCraft blocks access to local IP addresses for security. This means you can't normally access any
+HTTP server running on your computer. However, this may be useful for testing programs without having a remote
+server. You can unblock these IPs in the ComputerCraft config.
+
+## Minecraft 1.13 and later, CC:T 1.87.0 and later {#cc-1.87.0}
+The configuration file can be located at `serverconfig/computercraft-server.toml` inside the world folder on either
+single-player or multiplayer. Look for lines that look like this:
+
+```toml
+#A list of rules which control behaviour of the "http" API for specific domains or IPs.
+#Each rule is an item with a 'host' to match against, and a series of properties. The host may be a domain name ("pastebin.com"),
+#wildcard ("*.pastebin.com") or CIDR notation ("127.0.0.0/8"). If no rules, the domain is blocked.
+[[http.rules]]
+    host = "$private"
+    action = "deny"
+```
+
+On 1.95.0 and later, this will be a single entry with `host = "$private"`. On earlier versions, this will be a number of
+`[[http.rules]]` with various IP addresses. You will want to remove all of the `[[http.rules]]` entires that have
+`action = "deny"`. Then save the file and relaunch Minecraft (Server).
+
+Here's what it should look like after removing:
+
+```toml
+#A list of rules which control behaviour of the "http" API for specific domains or IPs.
+#Each rule is an item with a 'host' to match against, and a series of properties. The host may be a domain name ("pastebin.com"),
+#wildcard ("*.pastebin.com") or CIDR notation ("127.0.0.0/8"). If no rules, the domain is blocked.
+[[http.rules]]
+    #The maximum size (in bytes) that a computer can send or receive in one websocket packet.
+    max_websocket_message = 131072
+    host = "*"
+    #The maximum size (in bytes) that a computer can upload in a single request. This includes headers and POST text.
+    max_upload = 4194304
+    action = "allow"
+    #The maximum size (in bytes) that a computer can download in a single request. Note that responses may receive more data than allowed, but this data will not be returned to the client.
+    max_download = 16777216
+    #The period of time (in milliseconds) to wait before a HTTP request times out. Set to 0 for unlimited.
+    timeout = 30000
+```
+
+## Minecraft 1.13 and later, CC:T 1.86.2 and earlier {#cc-1.86.2}
+The configuration file for singleplayer is at `.minecraft/config/computercraft-common.toml`. Look for lines that look
+like this:
+
+```toml
+#A list of wildcards for domains or IP ranges that cannot be accessed through the "http" API on Computers.
+#If this is empty then all whitelisted domains will be accessible. Example: "*.github.com" will block access to all subdomains of github.com.
+#You can use domain names ("pastebin.com"), wilcards ("*.pastebin.com") or CIDR notation ("127.0.0.0/8").
+blacklist = ["127.0.0.0/8", "10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "fd00::/8"]
+```
+
+Remove everything inside the array, leaving the last line as `blacklist = []`. Then save the file and relaunch Minecraft.
+
+Here's what it should look like after removing:
+
+```toml
+#A list of wildcards for domains or IP ranges that cannot be accessed through the "http" API on Computers.
+#If this is empty then all whitelisted domains will be accessible. Example: "*.github.com" will block access to all subdomains of github.com.
+#You can use domain names ("pastebin.com"), wilcards ("*.pastebin.com") or CIDR notation ("127.0.0.0/8").
+blacklist = []
+```
+
+## Minecraft 1.12.2 and earlier {#mc-1.12}
+On singleplayer, the configuration file is located at `.minecraft\config\ComputerCraft.cfg`. On multiplayer, the
+configuration file is located at `<server folder>\config\ComputerCraft.cfg`. Look for lines that look like this:
+
+```ini
+# A list of wildcards for domains or IP ranges that cannot be accessed through the "http" API on Computers.
+# If this is empty then all explicitly allowed domains will be accessible. Example: "*.github.com" will block access to all subdomains of github.com.
+# You can use domain names ("pastebin.com"), wildcards ("*.pastebin.com") or CIDR notation ("127.0.0.0/8").
+S:blocked_domains <
+    127.0.0.0/8
+    10.0.0.0/8
+    172.16.0.0/12
+    192.168.0.0/16
+    fd00::/8
+ >
+```
+
+Delete everything between the `<>`, leaving the last line as `S:blocked_domains = <>`. Then save the file and relaunch
+Minecraft (Server).
+
+Here's what it should look like after removing:
+
+```ini
+# A list of wildcards for domains or IP ranges that cannot be accessed through the "http" API on Computers.
+# If this is empty then all explicitly allowed domains will be accessible. Example: "*.github.com" will block access to all subdomains of github.com.
+# You can use domain names ("pastebin.com"), wildcards ("*.pastebin.com") or CIDR notation ("127.0.0.0/8").
+S:blocked_domains <>
+```

doc/stub/fs.lua

@@ -1,6 +1,4 @@
----  The FS API allows you to manipulate files and the filesystem.
+--- @module fs
---
--- @module fs
 
 --- Returns true if a path is mounted to the parent filesystem.
 --

doc/stub/global.lua

@@ -62,7 +62,7 @@ function print(...) end
 -- @usage printError("Something went wrong!")
 function printError(...) end
 
---[[- Reads user input from the terminal, automatically handling arrow keys,
+--[[- Reads user input from the terminal. This automatically handles arrow keys,
 pasting, character replacement, history scrollback, auto-completion, and
 default values.
 
@@ -110,10 +110,15 @@ the prompt.
 ]]
 function read(replaceChar, history, completeFn, default) end
 
---- The ComputerCraft and Minecraft version of the current computer environment.
+--- Stores the current ComputerCraft and Minecraft versions.
+--
+-- Outside of Minecraft (for instance, in an emulator) @{_HOST} will contain the
+-- emulator's version instead.
 --
 -- For example, `ComputerCraft 1.93.0 (Minecraft 1.15.2)`.
--- @usage _HOST
+-- @usage Print the current computer's environment.
+--
+--     print(_HOST)
 -- @since 1.76
 _HOST = _HOST
 

doc/stub/http.lua

@@ -1,14 +1,13 @@
---- The http library allows communicating with web servers, sending and
+--- Make HTTP requests, sending and receiving data to a remote web server.
--- receiving data from them.
 --
 -- @module http
 -- @since 1.1
+-- @see local_ips To allow accessing servers running on your local network.
 
 --- Asynchronously make a HTTP request to the given url.
 --
--- This returns immediately, a [`http_success`](#http-success-event) or
+-- This returns immediately, a @{http_success} or @{http_failure} will be queued
--- [`http_failure`](#http-failure-event) will be queued once the request has
+-- once the request has completed.
--- completed.
 --
 -- @tparam      string url   The url to request
 -- @tparam[opt] string body  An optional string containing the body of the
@@ -112,9 +111,8 @@ function post(...) end
 
 --- Asynchronously determine whether a URL can be requested.
 --
--- If this returns `true`, one should also listen for [`http_check`
+-- If this returns `true`, one should also listen for @{http_check} which will
--- events](#http-check-event) which will container further information about
+-- container further information about whether the URL is allowed or not.
--- whether the URL is allowed or not.
 --
 -- @tparam string url The URL to check.
 -- @treturn true When this url is not invalid. This does not imply that it is
@@ -128,9 +126,8 @@ function checkURLAsync(url) end
 
 --- Determine whether a URL can be requested.
 --
--- If this returns `true`, one should also listen for [`http_check`
+-- If this returns `true`, one should also listen for @{http_check} which will
--- events](#http-check-event) which will container further information about
+-- container further information about whether the URL is allowed or not.
--- whether the URL is allowed or not.
 --
 -- @tparam string url The URL to check.
 -- @treturn true When this url is valid and can be requested via @{http.request}.
@@ -168,9 +165,8 @@ function websocket(url, headers) end
 
 --- Asynchronously open a websocket.
 --
--- This returns immediately, a [`websocket_success`](#websocket-success-event)
+-- This returns immediately, a @{websocket_success} or @{websocket_failure}
--- or [`websocket_failure`](#websocket-failure-event) will be queued once the
+-- will be queued once the request has completed.
--- request has completed.
 --
 -- @tparam string url The websocket url to connect to. This should have the
 -- `ws://` or `wss://` protocol.

src/main/java/dan200/computercraft/core/apis/FSAPI.java

@@ -30,8 +30,8 @@ import java.util.OptionalLong;
 import java.util.function.Function;
 
 /**
- * The FS API provides access to the computer's files and filesystem, allowing you to manipulate files, directories and
+ * Interact with the computer's files and filesystem, allowing you to manipulate files, directories and paths. This
- * paths. This includes:
+ * includes:
  *
  * <ul>
  * <li>**Reading and writing files:** Call {@link #open} to obtain a file "handle", which can be used to read from or

src/main/java/dan200/computercraft/core/apis/HTTPAPI.java

@@ -28,7 +28,7 @@ import java.util.Optional;
 import static dan200.computercraft.core.apis.TableHelper.*;
 
 /**
- * The http library allows communicating with web servers, sending and receiving data from them.
+ * Placeholder description, please ignore.
  *
  * @cc.module http
  * @hidden

src/main/java/dan200/computercraft/core/apis/RedstoneAPI.java

@@ -11,7 +11,7 @@ import dan200.computercraft.api.lua.LuaFunction;
 import dan200.computercraft.core.computer.ComputerSide;
 
 /**
- * Interact with redstone attached to this computer.
+ * Get and set redstone signals adjacent to this computer.
  *
  * 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

src/main/java/dan200/computercraft/core/apis/TermAPI.java

@@ -16,7 +16,8 @@ import dan200.computercraft.shared.util.Colour;
 import javax.annotation.Nonnull;
 
 /**
- * The Terminal API provides functions for writing text to the terminal and monitors, and drawing ASCII graphics.
+ * Interact with a computer's terminal or monitors, writing text and drawing
+ * ASCII graphics.
  *
  * @cc.module term
  */

src/main/resources/data/computercraft/lua/rom/apis/colors.lua

@@ -1,12 +1,13 @@
---[[- The Colors API allows you to manipulate sets of colors.
+--[[- Constants and functions for colour values, suitable for working with
+@{term} and @{redstone}.
 
-This is useful in conjunction with Bundled Cables from the RedPower mod, RedNet
+This is useful in conjunction with @{redstone.setBundledOutput|Bundled Cables}
-Cables from the MineFactory Reloaded mod, and colors on Advanced Computers and
+from mods like Project Red, and @{term.setTextColour|colors on Advanced
-Advanced Monitors.
+Computers and Advanced Monitors}.
 
-For the non-American English version just replace @{colors} with @{colours} and
+For the non-American English version just replace @{colors} with @{colours}.
-it will use the other API, colours which is exactly the same, except in British
+This alternative API is exactly the same, except the colours use British English
-English (e.g. @{colors.gray} is spelt @{colours.grey}).
+(e.g. @{colors.gray} is spelt @{colours.grey}).
 
 On basic terminals (such as the Computer and Monitor), all the colors are
 converted to grayscale. This means you can still use all 16 colors on the

src/main/resources/data/computercraft/lua/rom/apis/colours.lua

@@ -1,4 +1,4 @@
---- Colours for lovers of British spelling.
+--- An alternative version of @{colors} for lovers of British spelling.
 --
 -- @see colors
 -- @module colours

src/main/resources/data/computercraft/lua/rom/apis/command/commands.lua

@@ -1,21 +1,26 @@
---- The commands API allows your system to directly execute [Minecraft
+--[[- Execute [Minecraft commands][mc] and gather data from the results from
--- commands][mc] and gather data from the results.
+a command computer.
---
--- While one may use @{commands.exec} directly to execute a command, the
--- commands API also provides helper methods to execute every command. For
--- instance, `commands.say("Hi!")` is equivalent to `commands.exec("say Hi!")`.
---
--- @{commands.async} provides a similar interface to execute asynchronous
--- commands. `commands.async.say("Hi!")` is equivalent to
--- `commands.execAsync("Hi!")`.
---
--- [mc]: https://minecraft.gamepedia.com/Commands
---
--- @module commands
--- @usage Set the block above this computer to stone:
---
---     commands.setblock("~", "~1", "~", "minecraft:stone")
 
+:::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
+instance, `commands.say("Hi!")` is equivalent to `commands.exec("say Hi!")`.
+
+@{commands.async} provides a similar interface to execute asynchronous
+commands. `commands.async.say("Hi!")` is equivalent to
+`commands.execAsync("Hi!")`.
+
+[mc]: https://minecraft.gamepedia.com/Commands
+
+@module commands
+@usage Set the block above this computer to stone:
+
+    commands.setblock("~", "~1", "~", "minecraft:stone")
+]]
 if not commands then
     error("Cannot load command API on normal computer", 2)
 end

src/main/resources/data/computercraft/lua/rom/apis/disk.lua

@@ -1,4 +1,4 @@
---[[- The Disk API allows you to interact with disk drives.
+--[[- Interact with disk drives.
 
 These functions can operate on locally attached or remote disk drives. To use a
 locally attached drive, specify “side” as one of the six sides (e.g. `left`); to

src/main/resources/data/computercraft/lua/rom/apis/gps.lua

@@ -1,5 +1,5 @@
---[[- The GPS API provides a method for turtles and computers to retrieve their
+--[[- Use @{modem|modems} to locate the position of the current turtle or
-own locations.
+computers.
 
 It broadcasts a PING message over @{rednet} and wait for responses. In order for
 this system to work, there must be at least 4 computers used as gps hosts which

src/main/resources/data/computercraft/lua/rom/apis/help.lua

@@ -1,4 +1,4 @@
---- Provides an API to read help files.
+--- Find help files on the current computer.
 --
 -- @module help
 -- @since 1.2

src/main/resources/data/computercraft/lua/rom/apis/keys.lua

@@ -1,5 +1,4 @@
---- The Keys API provides a table of numerical codes corresponding to keyboard
+--- Constants for all keyboard "key codes", as queued by the @{key} event.
--- keys, suitable for decoding key events.
 --
 -- These values are not guaranteed to remain the same between versions. It is
 -- recommended that you use the constants provided by this file, rather than

src/main/resources/data/computercraft/lua/rom/apis/paintutils.lua

@@ -1,5 +1,5 @@
---- An API for advanced systems which can draw pixels and lines, load and draw
+--- Utilities for drawing more complex graphics, such as pixels, lines and
--- image files. You can use the `colors` API for easier color manipulation.
+-- images.
 --
 -- @module paintutils
 -- @since 1.45

src/main/resources/data/computercraft/lua/rom/apis/parallel.lua

@@ -1,8 +1,8 @@
---[[- Provides a simple implementation of multitasking.
+--[[- A simple way to run several functions at once.
 
 Functions are not actually executed simultaniously, but rather this API will
-automatically switch between them whenever they yield (eg whenever they call
+automatically switch between them whenever they yield (e.g. whenever they call
-@{coroutine.yield}, or functions that call that - eg @{os.pullEvent} - or
+@{coroutine.yield}, or functions that call that - such as @{os.pullEvent} - or
 functions that call that, etc - basically, anything that causes the function
 to "pause").
 
@@ -12,6 +12,27 @@ script to pause - eg @{os.sleep}, @{rednet.receive}, most of the @{turtle} API,
 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)
+```
+
+:::
+
 @module parallel
 @since 1.2
 ]]

src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua

@@ -1,4 +1,6 @@
---[[- Peripherals are blocks (or turtle and pocket computer upgrades) which can
+--[[- Find and control peripherals attached to this computer.
+
+Peripherals are blocks (or turtle and pocket computer upgrades) which can
 be controlled by a computer. For instance, the @{speaker} peripheral allows a
 computer to play music and the @{monitor} peripheral allows you to display text
 in the world.

src/main/resources/data/computercraft/lua/rom/apis/rednet.lua

@@ -1,6 +1,6 @@
---[[- The Rednet API allows computers to communicate between each other by using
+--[[- Communicate with other computers by using @{modem|modems}. @{rednet}
-@{modem|modems}. It provides a layer of abstraction on top of the main @{modem}
+provides a layer of abstraction on top of the main @{modem} peripheral, making
-peripheral, making it slightly easier to use.
+it slightly easier to use.
 
 ## Basic usage
 In order to send a message between two computers, each computer must have a

src/main/resources/data/computercraft/lua/rom/apis/settings.lua

@@ -1,5 +1,4 @@
---- The settings API allows to store values and save them to a file for
+--- Read and write configuration options for CraftOS and your programs.
--- persistent configurations for CraftOS and your programs.
 --
 -- By default, the settings API will load its configuration from the
 -- `/.settings` file. One can then use @{settings.save} to update the file.

src/main/resources/data/computercraft/lua/rom/apis/term.lua

@@ -1,7 +1,4 @@
---- The Terminal API provides functions for writing text to the terminal and
+--- @module term
--- monitors, and drawing ASCII graphics.
---
--- @module term
 
 local expect = dofile("rom/modules/main/cc/expect.lua").expect
 

src/main/resources/data/computercraft/lua/rom/apis/textutils.lua

@@ -1,5 +1,4 @@
---- The @{textutils} API provides helpful utilities for formatting and
+--- Helpful utilities for formatting and manipulating strings.
--- manipulating strings.
 --
 -- @module textutils
 -- @since 1.2

src/main/resources/data/computercraft/lua/rom/apis/vector.lua

@@ -1,4 +1,6 @@
---- The vector API provides methods to create and manipulate vectors.
+--- A basic 3D vector type and some common vector operations. This may be useful
+-- when working with coordinates in Minecraft's world (such as those from the
+-- @{gps} API).
 --
 -- An introduction to vectors can be found on [Wikipedia][wiki].
 --

src/main/resources/data/computercraft/lua/rom/apis/window.lua

@@ -1,32 +1,33 @@
---- The Window API allows easy definition of spaces within the display that can
+--[[- A @{term.Redirect|terminal redirect} occupying a smaller area of an
--- be written/drawn to, then later redrawn/repositioned/etc as need be. The API
+existing terminal. This allows for easy definition of spaces within the display
--- itself contains only one function, @{window.create}, which returns the
+that can be written/drawn to, then later redrawn/repositioned/etc as need
--- windows themselves.
+be. The API itself contains only one function, @{window.create}, which returns
---
+the windows themselves.
--- Windows are considered terminal objects - as such, they have access to nearly
+
--- all the commands in the term API (plus a few extras of their own, listed
+Windows are considered terminal objects - as such, they have access to nearly
--- within said API) and are valid targets to redirect to.
+all the commands in the term API (plus a few extras of their own, listed within
---
+said API) and are valid targets to redirect to.
--- Each window has a "parent" terminal object, which can be the computer's own
+
--- display, a monitor, another window or even other, user-defined terminal
+Each window has a "parent" terminal object, which can be the computer's own
--- objects. Whenever a window is rendered to, the actual screen-writing is
+display, a monitor, another window or even other, user-defined terminal
--- performed via that parent (or, if that has one too, then that parent, and so
+objects. Whenever a window is rendered to, the actual screen-writing is
--- forth). Bear in mind that the cursor of a window's parent will hence be moved
+performed via that parent (or, if that has one too, then that parent, and so
--- around etc when writing a given child window.
+forth). Bear in mind that the cursor of a window's parent will hence be moved
---
+around etc when writing a given child window.
--- Windows retain a memory of everything rendered "through" them (hence acting
+
--- as display buffers), and if the parent's display is wiped, the window's
+Windows retain a memory of everything rendered "through" them (hence acting as
--- content can be easily redrawn later. A window may also be flagged as
+display buffers), and if the parent's display is wiped, the window's content can
--- invisible, preventing any changes to it from being rendered until it's
+be easily redrawn later. A window may also be flagged as invisible, preventing
--- flagged as visible once more.
+any changes to it from being rendered until it's flagged as visible once more.
---
+
--- A parent terminal object may have multiple children assigned to it, and
+A parent terminal object may have multiple children assigned to it, and windows
--- windows may overlap. For example, the Multishell system functions by
+may overlap. For example, the Multishell system functions by assigning each tab
--- assigning each tab a window covering the screen, each using the starting
+a window covering the screen, each using the starting terminal display as its
--- terminal display as its parent, and only one of which is visible at a time.
+parent, and only one of which is visible at a time.
---
+
--- @module window
+@module window
--- @since 1.6
+@since 1.6
+]]
 
 local expect = dofile("rom/modules/main/cc/expect.lua").expect
 

src/main/resources/data/computercraft/lua/rom/modules/main/cc/audio/dfpwm.lua

@@ -1,5 +1,5 @@
 --[[-
-Provides utilities for converting between streams of DFPWM audio data and a list of amplitudes.
+Convert between streams of DFPWM audio data and a list of amplitudes.
 
 DFPWM (Dynamic Filter Pulse Width Modulation) is an audio codec designed by GreaseMonkey. It's a relatively compact
 format compared to raw PCM data, only using 1 bit per sample, but is simple enough to simple enough to encode and decode

src/main/resources/data/computercraft/lua/rom/modules/main/cc/image/nft.lua

@@ -1,8 +1,8 @@
---- Provides utilities for working with "nft" images.
+--- Read and draw nbt ("Nitrogen Fingers Text") images.
 --
 -- nft ("Nitrogen Fingers Text") is a file format for drawing basic images.
 -- Unlike the images that @{paintutils.parseImage} uses, nft supports coloured
--- text.
+-- text as well as simple coloured pixels.
 --
 -- @module cc.image.nft
 -- @since 1.90.0

src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua

@@ -1,5 +1,5 @@
---[[- Provides a "pretty printer", for rendering data structures in an
+--[[- A pretty printer for rendering data structures in an aesthetically
-aesthetically pleasing manner.
+pleasing manner.
 
 In order to display something using @{cc.pretty}, you build up a series of
 @{Doc|documents}. These behave a little bit like strings; you can concatenate

src/main/resources/data/computercraft/lua/rom/modules/main/cc/require.lua

@@ -1,5 +1,5 @@
---[[- This provides a pure Lua implementation of the builtin @{require} function
+--[[- A pure Lua implementation of the builtin @{require} function and
-and @{package} library.
+@{package} library.
 
 Generally you do not need to use this module - it is injected into the every
 program's environment. However, it may be useful when building a custom shell or

src/web/index.tsx

@@ -9,6 +9,8 @@ import exampleNft from "./mount/example.nft";
 import exampleAudioLicense from "./mount/example.dfpwm.LICENSE";
 import exampleAudioUrl from "./mount/example.dfpwm";
 
+import "./prism.js";
+
 const defaultFiles: { [filename: string]: string } = {
     ".settings": settingsFile,
     "startup.lua": startupFile,
@@ -76,7 +78,9 @@ class Window extends Component<WindowProps, WindowState> {
             const snippet = element.getAttribute("data-snippet");
             if (snippet) this.snippets[snippet] = example;
 
-            if (element.getAttribute("data-lua-kind") == "expr") {
+            // We attempt to pretty-print the result of a function _except_ when the function
+            // is print. This is pretty ugly, but prevents the confusing trailing "1".
+            if (element.getAttribute("data-lua-kind") == "expr" && !example.startsWith("print(")) {
                 example = exprTemplate.replace("__expr__", example);
             }
 

src/web/styles.css

@@ -21,7 +21,7 @@ table th {
     background-color: var(--background-2);
 }
 
-pre.highlight.highlight-lua {
+pre.highlight {
     position: relative;
 }