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/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