From 9499654757c747d10664cf2d919e2a0f63319020 Mon Sep 17 00:00:00 2001
From: Jonathan Coates <git@squiddev.cc>
Date: Wed, 24 Jun 2020 12:10:54 +0100
Subject: [PATCH] Add documentation for peripherals

No clue how we're going to do this for the dynamic peripheral system
if/when that ships, but this is a good first stage.

Like the Java APIs, this relies on stub files, so we can't link to the
implementation which is a bit of a shame. However, it's a good first
step.
---
 doc/stub/computer.lua                         | 27 +++++++
 doc/stub/drive.lua                            | 12 +++
 doc/stub/modem.lua                            | 73 +++++++++++++++++++
 doc/stub/monitor.lua                          | 32 ++++++++
 doc/stub/printer.lua                          | 11 +++
 doc/styles.css                                |  7 +-
 illuaminate.sexp                              | 11 ++-
 .../computercraft/lua/rom/apis/peripheral.lua |  4 +-
 .../computercraft/lua/rom/apis/textutils.lua  |  2 +-
 9 files changed, 174 insertions(+), 5 deletions(-)
 create mode 100644 doc/stub/computer.lua
 create mode 100644 doc/stub/drive.lua
 create mode 100644 doc/stub/modem.lua
 create mode 100644 doc/stub/monitor.lua
 create mode 100644 doc/stub/printer.lua

diff --git a/doc/stub/computer.lua b/doc/stub/computer.lua
new file mode 100644
index 000000000..421fae547
--- /dev/null
+++ b/doc/stub/computer.lua
@@ -0,0 +1,27 @@
+--- A computer or turtle wrapped as a peripheral.
+--
+-- This allows for basic interaction with adjacent computers. Computers wrapped
+-- as peripherals will have the type `computer` while turtles will be `turtle`.
+--
+-- @module[kind=peripheral] computer
+
+function turnOn() end --- Turn the other computer on.
+function shutdown() end --- Shutdown the other computer.
+function reboot() end --- Reboot or turn on the other computer.
+
+--- Get the other computer's ID.
+--
+-- @treturn number The computer's ID.
+-- @see os.getComputerID To get your computer ID.
+function getID() end
+
+--- Determine if the other computer is on.
+--
+-- @treturn boolean If the computer is on.
+function isOn() end
+
+--- Get the other computer's label.
+--
+-- @treturn string|nil The computer's label.
+-- @see os.getComputerLabel To get your label.
+function getLabel() end
diff --git a/doc/stub/drive.lua b/doc/stub/drive.lua
new file mode 100644
index 000000000..f9c5ac469
--- /dev/null
+++ b/doc/stub/drive.lua
@@ -0,0 +1,12 @@
+--- @module[kind=peripheral] drive
+
+function isDiskPresent() end
+function getDiskLabel() end
+function setDiskLabel(label) end
+function hasData() end
+function getMountPath() end
+function hasAudio() end
+function getAudioTitle() end
+function playAudio() end
+function ejectDisk() end
+function getDiskID() end
diff --git a/doc/stub/modem.lua b/doc/stub/modem.lua
new file mode 100644
index 000000000..874568c51
--- /dev/null
+++ b/doc/stub/modem.lua
@@ -0,0 +1,73 @@
+--- @module[kind=peripheral] modem
+
+function open(channel) end
+function isOpen(channel) end
+function close(channel) end
+
+--- Close all open channels.
+function closeAll() end
+
+function transmit(channel, replyChannel, payload) end
+
+--- Determine if this is a wired or wireless modem.
+--
+-- Some methods (namely those dealing with wired networks and remote
+-- peripherals) are only available on wired modems.
+--
+-- @treturn boolean @{true} if this is a wireless modem.
+function isWireless() end
+
+-- Wired modem only
+
+--- List all remote peripherals on the wired network.
+--
+-- If this computer is attached to the network, it _will not_ be included in
+-- this list.
+--
+-- > **Important:** This function only appears on wired modems. Check
+-- > @{isWireless} returns false before calling it.
+--
+-- @treturn { string... } Remote peripheral names on the network.
+function getNamesRemote(name) end
+
+--- Determine if a peripheral is available on this wired network.
+--
+-- > **Important:** This function only appears on wired modems. Check
+-- > @{isWireless} returns false before calling it.
+--
+-- @tparam string name The peripheral's name.
+-- @treturn boolean If a peripheral is present with the given name.
+-- @see peripheral.isPresent
+function isPresentRemote(name) end
+
+--- Get the type of a peripheral is available on this wired network.
+--
+-- > **Important:** This function only appears on wired modems. Check
+-- > @{isWireless} returns false before calling it.
+--
+-- @tparam string name The peripheral's name.
+-- @treturn string|nil The peripheral's type, or `nil` if it is not present.
+-- @see peripheral.getType
+function getTypeRemote(name) end
+
+--- Call a method on a peripheral on this wired network.
+--
+-- > **Important:** This function only appears on wired modems. Check
+-- > @{isWireless} returns false before calling it.
+--
+-- @tparam string remoteName The name of the peripheral to invoke the method on.
+-- @tparam string method The name of the method
+-- @param ... Additional arguments to pass to the method
+-- @return The return values of the peripheral method.
+-- @see peripheral.call
+function callRemote(remoteName, method, ...) end
+
+--- 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.
+--
+-- > **Important:** This function only appears on wired modems. Check
+-- > @{isWireless} returns false before calling it.
+--
+-- @treturn string|nil The current computer's name on the wired network.
+function getNameLocal() end
diff --git a/doc/stub/monitor.lua b/doc/stub/monitor.lua
new file mode 100644
index 000000000..cea79560d
--- /dev/null
+++ b/doc/stub/monitor.lua
@@ -0,0 +1,32 @@
+--[[- 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.
+
+Monitors act as @{term.Redirect|terminal redirects} and so expose the same
+methods, as well as several additional ones, which are documented below.
+
+Like computers, monitors come in both normal (no colour) and advanced (colour)
+varieties.
+
+@module[kind=peripheral] monitor
+@usage Write "Hello, world!" to an adjacent monitor:
+
+    local monitor = peripheral.find("monitor")
+    monitor.setCursorPos(1, 1)
+    monitor.write("Hello, world!")
+]]
+
+
+--- Set the scale of this monitor. A larger scale will result in the monitor
+-- having a lower resolution, but display text much larger.
+--
+-- @tparam number scale The monitor's scale. This must be a multiple of 0.5
+-- between 0.5 and 5.
+-- @throws If the scale is out of range.
+-- @see getTextScale
+function setTextScale(scale) end
+
+--- Get the monitor's current text scale.
+--
+-- @treturn number The monitor's current scale.
+function getTextScale() end
diff --git a/doc/stub/printer.lua b/doc/stub/printer.lua
new file mode 100644
index 000000000..674aab13a
--- /dev/null
+++ b/doc/stub/printer.lua
@@ -0,0 +1,11 @@
+--- @module[kind=peripheral] printer
+
+function write(text) end
+function getCursorPos() end
+function setCursorPos(x, y) end
+function getPageSize() end
+function newPage() end
+function endPage() end
+function setPageTitle(title) end
+function getInkLevel() end
+function getPaperLevel() end
diff --git a/doc/styles.css b/doc/styles.css
index 436a8c535..2bcc830cc 100644
--- a/doc/styles.css
+++ b/doc/styles.css
@@ -51,7 +51,12 @@ h4 { font-size: 1.06em; }
 a, a:visited, a:active { font-weight: bold; color: #004080; text-decoration: none; }
 a:hover { text-decoration: underline; }
 
-blockquote { margin-left: 3em; }
+blockquote {
+    padding: 0.3em;
+    margin: 1em 0;
+    background: #f0f0f0;
+    border-left: solid 0.5em #ccc;
+}
 
 /* Stop sublists from having initial vertical space */
 ul ul { margin-top: 0px; }
diff --git a/illuaminate.sexp b/illuaminate.sexp
index 769eba175..75e011de6 100644
--- a/illuaminate.sexp
+++ b/illuaminate.sexp
@@ -12,6 +12,9 @@
   (index doc/index.md)
   (source-link https://github.com/SquidDev-CC/CC-Tweaked/blob/${commit}/${path}#L${line})
 
+  (module-kinds
+    (peripheral Peripherals))
+
   (library-path
     /doc/stub/
 
@@ -70,11 +73,17 @@
 
 ;; Suppress warnings for currently undocumented modules.
 (at
-  (/doc/stub/fs.lua
+  (; Java APIs
+   /doc/stub/fs.lua
    /doc/stub/http.lua
    /doc/stub/os.lua
    /doc/stub/term.lua
    /doc/stub/turtle.lua
+   ; Peripherals
+   /doc/stub/drive.lua
+   /doc/stub/modem.lua
+   /doc/stub/printer.lua
+   ; Lua APIs
    /src/main/resources/*/computercraft/lua/rom/apis/io.lua
    /src/main/resources/*/computercraft/lua/rom/apis/window.lua)
 
diff --git a/src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua b/src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua
index c737a915a..d8be09ad3 100644
--- a/src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua
+++ b/src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua
@@ -23,7 +23,7 @@ local sides = rs.getSides()
 -- listed as the side it is attached to. If a device is attached via a Wired
 -- Modem, then it'll be reported according to its name on the wired network.
 --
--- @treturn table A list of the names of all attached peripherals.
+-- @treturn { string... } A list of the names of all attached peripherals.
 function getNames()
     local results = {}
     for n = 1, #sides do
@@ -96,7 +96,7 @@ end
 --- Get all available methods for the peripheral with the given name.
 --
 -- @tparam string name The name of the peripheral to find.
--- @treturn table|nil A list of methods provided by this peripheral, or `nil` if
+-- @treturn { string... }|nil A list of methods provided by this peripheral, or `nil` if
 -- it is not present.
 function getMethods(name)
     expect(1, name, "string")
diff --git a/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua b/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua
index d087c570c..0e96a287d 100644
--- a/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua
+++ b/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua
@@ -1,4 +1,4 @@
---- The `textutils` API provides helpful utilities for formatting and
+--- The @{textutils} API provides helpful utilities for formatting and
 -- manipulating strings.
 --
 -- @module textutils