An initial stab at documentation generation (#360)

This adds documentation comments to many of CC's Lua APIs, and
a couple of the Java ones, through the use of stubs. We then
export these to HTML using illuaminate [1] and upload them to our
documentation site [2].

Uploads currently occur on pushes to master and any release/tag. The
site is entirely static - there is no way to switch between versions,
etc... but hopefully we can improve this in the future.

[1]: github.com/SquidDev/illuaminate/
[2]: https://tweaked.cc/

doc/stub/commands.lua

@@ -0,0 +1,6 @@
+function exec(command) end
+function execAsync(commad) end
+function list() end
+function getBlockPosition() end
+function getBlockInfos(min_x, min_y, min_z, max_x, max_y, max_z) end
+function getBlockInfo(x, y, z) end

doc/stub/fs.lua

@@ -0,0 +1,42 @@
+---  The FS API allows you to manipulate files and the filesystem.
+--
+-- @module fs
+
+function list(path) end
+function combine(base, child) end
+function getName(path) end
+function getSize(path) end
+function exists(path) end
+function isDir(path) end
+function isReadOnly(path) end
+function makeDir(path) end
+function move(from, to) end
+function copy(from, to) end
+function delete(path) end
+function open(path, mode) end
+function getDrive(path) end
+function getFreeSpace(path) end
+function find(pattern) end
+function getDir(path) end
+
+--- A file handle which can be read from.
+--
+-- @type ReadHandle
+-- @see fs.open
+local ReadHandle = {}
+function ReadHandle.read(count) end
+function ReadHandle.readAll() end
+function ReadHandle.readLine(with_trailing) end
+function ReadHandle.seek(whence, offset) end
+function ReadHandle.close() end
+
+--- A file handle which can be written to.
+--
+-- @type WriteHandle
+-- @see fs.open
+local WriteHandle = {}
+function WriteHandle.write(text) end
+function WriteHandle.writeLine(text) end
+function WriteHandle.flush(text) end
+function WriteHandle.seek(whence, offset) end
+function WriteHandle.close() end

doc/stub/http.lua

@@ -0,0 +1,213 @@
+--- The http library allows communicating with web servers, sending and
+-- receiving data from them.
+--
+-- #### `http_check` event
+--
+-- @module http
+
+--- Asynchronously make a HTTP request to the given url.
+--
+-- This returns immediately, a [`http_success`](#http-success-event) or
+-- [`http_failure`](#http-failure-event) will be queued once the request has
+-- completed.
+--
+-- @tparam      string url   The url to request
+-- @tparam[opt] string body  An optional string containing the body of the
+-- request. If specified, a `POST` request will be made instead.
+-- @tparam[opt] { [string] = string } headers Additional headers to send as part
+-- of this request.
+-- @tparam[opt] boolean binary Whether to make a binary HTTP request. If true,
+-- the body will not be UTF-8 encoded, and the received response will not be
+-- decoded.
+--
+-- @tparam[2] {
+--   url = string, body? = string, headers? = { [string] = string },
+--   binary? = boolean, method? = string, redirect? = boolean,
+-- } request Options for the request.
+--
+-- This table form is an expanded version of the previous syntax. All arguments
+-- from above are passed in as fields instead (for instance,
+-- `http.request("https://example.com")` becomes `http.request { url =
+-- "https://example.com" }`).
+--
+-- This table also accepts several additional options:
+--
+--  - `method`: Which HTTP method to use, for instance `"PATCH"` or `"DELETE"`.
+--  - `redirect`: Whether to follow HTTP redirects. Defaults to true.
+--
+-- @see http.get  For a synchronous way to make GET requests.
+-- @see http.post For a synchronous way to make POST requests.
+function request(...) end
+
+--- Make a HTTP GET request to the given url.
+--
+-- @tparam string url   The url to request
+-- @tparam[opt] { [string] = string } headers Additional headers to send as part
+-- of this request.
+-- @tparam[opt] boolean binary Whether to make a binary HTTP request. If true,
+-- the body will not be UTF-8 encoded, and the received response will not be
+-- decoded.
+--
+-- @tparam[2] {
+--   url = string, headers? = { [string] = string },
+--   binary? = boolean, method? = string, redirect? = boolean,
+-- } request Options for the request. See @{http.request} for details on how
+-- these options behave.
+--
+-- @treturn Response The resulting http response, which can be read from.
+-- @treturn[2] nil When the http request failed, such as in the event of a 404
+-- error or connection timeout.
+-- @treturn string A message detailing why the request failed.
+-- @treturn Response|nil The failing http response, if available.
+--
+-- @usage Make a request to [example.computercraft.cc](https://example.computercraft.cc),
+-- and print the returned page.
+-- ```lua
+-- local request = http.get("https://example.computercraft.cc")
+-- print(request.readAll())
+-- -- => HTTP is working!
+-- request.close()
+-- ```
+function get(...) end
+
+--- Make a HTTP POST request to the given url.
+--
+-- @tparam string url   The url to request
+-- @tparam string body  The body of the POST request.
+-- @tparam[opt] { [string] = string } headers Additional headers to send as part
+-- of this request.
+-- @tparam[opt] boolean binary Whether to make a binary HTTP request. If true,
+-- the body will not be UTF-8 encoded, and the received response will not be
+-- decoded.
+--
+-- @tparam[2] {
+--   url = string, body? = string, headers? = { [string] = string },
+--   binary? = boolean, method? = string, redirect? = boolean,
+-- } request Options for the request. See @{http.request} for details on how
+-- these options behave.
+--
+-- @treturn Response The resulting http response, which can be read from.
+-- @treturn[2] nil When the http request failed, such as in the event of a 404
+-- error or connection timeout.
+-- @treturn string A message detailing why the request failed.
+-- @treturn Response|nil The failing http response, if available.
+function post(...) end
+
+--- A http response. This acts very much like a @{fs.ReadHandle|file}, though
+-- provides some http specific methods.
+--
+-- #### `http_success` event
+-- #### `http_failure` event
+--
+-- @type Response
+-- @see http.request On how to make a http request.
+local Response = {}
+
+--- Returns the response code and response message returned by the server
+--
+-- @treturn number The response code (i.e. 200)
+-- @treturn string The response message (i.e. "OK")
+function Response.getResponseCode() end
+
+--- Get a table containing the response's headers, in a format similar to that
+-- required by @{http.request}. If multiple headers are sent with the same
+-- name, they will be combined with a comma.
+--
+-- @treturn { [string]=string } The response's headers.
+-- Make a request to [example.computercraft.cc](https://example.computercraft.cc),
+-- and print the returned headers.
+-- ```lua
+-- local request = http.get("https://example.computercraft.cc")
+-- print(textutils.serialize(request.getResponseHeaders()))
+-- -- => {
+-- --   [ "Content-Type" ] = "text/plain; charset=utf8",
+-- --   [ "content-length" ] = 17,
+-- --   ...
+-- -- }
+-- request.close()
+-- ```
+function Response.getResponseHeaders() end
+
+function Response.read(count) end
+function Response.readAll() end
+function Response.readLine(with_trailing) end
+function Response.seek(whence, offset) end
+function Response.close() end
+
+--- Asynchronously determine whether a URL can be requested.
+--
+-- If this returns `true`, one should also listen for [`http_check`
+-- events](#http-check-event) which will container further information about
+-- 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
+-- allowed - see the comment above.
+-- @treturn[2] false When this url is invalid.
+-- @treturn string A reason why this URL is not valid (for instance, if it is
+-- malformed, or blocked).
+--
+-- @see http.checkURL For a synchronous version.
+function checkURLAsync(url) end
+
+--- Determine whether a URL can be requested.
+--
+-- If this returns `true`, one should also listen for [`http_check`
+-- events](#http-check-event) which will container further information about
+-- 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}.
+-- @treturn[2] false When this url is invalid.
+-- @treturn string A reason why this URL is not valid (for instance, if it is
+-- malformed, or blocked).
+--
+-- @see http.checkURLAsync For an asynchronous version.
+--
+-- @usage
+-- ```lua
+-- print(http.checkURL("https://example.computercraft.cc/"))
+-- -- => true
+-- print(http.checkURL("http://localhost/"))
+-- -- => false Domain not permitted
+-- print(http.checkURL("not a url"))
+-- -- => false URL malformed
+-- ```
+function checkURL(url) end
+
+--- Open a websocket.
+--
+-- @tparam string url The websocket url to connect to. This should have the
+-- `ws://` or `wss://` protocol.
+-- @tparam[opt] { [string] = string } headers Additional headers to send as part
+-- of the initial websocket connection.
+--
+-- @treturn Websocket The websocket connection.
+-- @treturn[2] false If the websocket connection failed.
+-- @treturn string An error message describing why the connection failed.
+function websocket(url, headers) end
+
+--- Asynchronously open a websocket.
+--
+-- This returns immediately, a [`websocket_success`](#websocket-success-event)
+-- or [`websocket_failure`](#websocket-failure-event) will be queued once the
+-- request has completed.
+--
+-- @tparam string url The websocket url to connect to. This should have the
+-- `ws://` or `wss://` protocol.
+-- @tparam[opt] { [string] = string } headers Additional headers to send as part
+-- of the initial websocket connection.
+function websocketAsync(url, headers) end
+
+
+
+--- A websocket, which can be used to send an receive messages with a web
+-- server.
+--
+-- @type Websocket
+-- @see http.websocket On how to open a websocket.
+local Websocket = {}
+
+function Websocket.send(message, binary) end
+function Websocket.receive() end
+function Websocket.close() end

doc/stub/os.lua

@@ -0,0 +1,17 @@
+function queueEvent(event, ...) end
+function startTimer(delay) end
+function setAlarm(time) end
+function shutdown() end
+function reboot() end
+function getComputerID() end
+computerID = getComputerID
+function setComputerLabel(label) end
+function getComputerLabel() end
+computerLabel = getComputerLabel
+function clock() end
+function time(timezone) end
+function day(timezone) end
+function cancelTimer(id) end
+function cancelAlarm(id) end
+function epoch(timezone) end
+function date(format, time) end

doc/stub/redstone.lua

@@ -0,0 +1,14 @@
+function getSides() end
+function setOutput(side, on) end
+function getOutput(side) end
+function getInput(side) end
+function setBundledOutput(side, output) end
+function getBundledOutput(side) end
+function getBundledInput(side) end
+function testBundledInput(side, mask) end
+function setAnalogOutput(side, value) end
+setAnalogueOutput = setAnalogOutput
+function getAnalogOutput(sid) end
+getAnalogueOutput = getAnalogOutput
+function getAnalogInput(side) end
+getAnalogueInput = getAnaloguInput

doc/stub/term.lua

@@ -0,0 +1,52 @@
+function write(text) end
+function scroll(lines) end
+function setCursorPos(x, y) end
+function setCursorBlink(blink) end
+function getCursorPos() end
+function getSize() end
+function clear() end
+function clearLine() end
+function setTextColour(colour) end
+setTextColor = setTextColour
+function setBackgroundColour(colour) end
+setBackgroundColor = setBackgroundColour
+function isColour() end
+isColor = isColour
+function getTextColour() end
+getTextColor = getTextColor
+function getBackgroundColour() end
+getBackgroundColour = getBackgroundColour
+function blit(text, text_colours, background_colours) end
+function setPaletteColour(colour, ...) end
+setPaletteColour = setPaletteColour
+function getPaletteColour(colour, ...) end
+getPaletteColour = getPaletteColour
+function nativePaletteColour(colour) end
+nativePaletteColour = nativePaletteColour
+
+--- @type Redirect
+local Redirect = {}
+
+Redirect.write = write
+Redirect.scroll = scroll
+Redirect.setCursorPos = setCursorPos
+Redirect.setCursorBlink = setCursorBlink
+Redirect.getCursorPos = getCursorPos
+Redirect.getSize = getSize
+Redirect.clear = clear
+Redirect.clearLine = clearLine
+Redirect.setTextColour = setTextColour
+Redirect.setTextColor = setTextColor
+Redirect.setBackgroundColour = setBackgroundColour
+Redirect.setBackgroundColor = setBackgroundColor
+Redirect.isColour = isColour
+Redirect.isColor = isColor
+Redirect.getTextColour = getTextColour
+Redirect.getTextColor = getTextColor
+Redirect.getBackgroundColour = getBackgroundColour
+Redirect.getBackgroundColor = getBackgroundColor
+Redirect.blit = blit
+Redirect.setPaletteColour = setPaletteColour
+Redirect.setPaletteColor = setPaletteColor
+Redirect.getPaletteColour = getPaletteColour
+Redirect.getPaletteColor = getPaletteColor

doc/stub/turtle.lua

@@ -0,0 +1,42 @@
+function forward() end
+function back() end
+function up() end
+function down() end
+function turnLeft() end
+function turnRight() end
+function dig(side) end
+function digUp(side) end
+function digDown(side) end
+function place() end
+function placeUp() end
+function placeDown() end
+function drop(count) end
+function select(slot) end
+function getItemCount(slot) end
+function getItemSpace(slot) end
+function detect() end
+function detectUp() end
+function detectDown() end
+function compare() end
+function compareUp() end
+function compareDown() end
+function attack(side) end
+function attackUp(side) end
+function attackDown(side) end
+function dropUp(count) end
+function dropDown(count) end
+function suck(count) end
+function suckUp(count) end
+function suckDown(count) end
+function getFuelLevel() end
+function refuel(count) end
+function compareTo(slot) end
+function transferTo(slot, count) end
+function getSelectedSlot() end
+function getFuelLimit() end
+function equipLeft() end
+function equipRight() end
+function inspect() end
+function inspectUp() end
+function inspectDown() end
+function getItemDetail(slot) end