A small amount of Lua documentation

I'd forgotten how tedious this was. I can't say any of these docs are
especially good, but it's something.

doc/stub/http.lua

@@ -199,8 +199,6 @@ function websocket(url, headers) end
 -- 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.
 --
@@ -208,6 +206,24 @@ function websocketAsync(url, headers) end
 -- @see http.websocket On how to open a websocket.
 local Websocket = {}
 
+--- Send a websocket message to the connected server.
+--
+-- @tparam string message The message to send.
+-- @tparam[opt] boolean binary Whether this message should be treated as a
+-- binary string, rather than encoded text.
+-- @throws If the websocket has been closed.
 function Websocket.send(message, binary) end
-function Websocket.receive() end
+
+--- Wait for a message from the server.
+--
+-- @tparam[opt] number timeout The number of seconds to wait if no message is
+-- received.
+-- @treturn[1] string The received message.
+-- @treturn boolean If this was a binary message.
+-- @treturn[2] nil If the websocket was closed while waiting, or if we timed out.
+-- @throws If the websocket has been closed.
+function Websocket.receive(timeout) end
+
+--- Close this websocket. This will terminate the connection, meaning messages
+-- can no longer be sent or received along it.
 function Websocket.close() end

doc/stub/turtle.lua

@@ -1,42 +1,230 @@
+--- Move the turtle forward one block.
+-- @treturn boolean Whether the turtle could successfully move.
+-- @treturn string|nil The reason the turtle could not move.
 function forward() end
+
+--- Move the turtle backwards one block.
+-- @treturn boolean Whether the turtle could successfully move.
+-- @treturn string|nil The reason the turtle could not move.
 function back() end
+
+--- Move the turtle up one block.
+-- @treturn boolean Whether the turtle could successfully move.
+-- @treturn string|nil The reason the turtle could not move.
 function up() end
+
+--- Move the turtle down one block.
+-- @treturn boolean Whether the turtle could successfully move.
+-- @treturn string|nil The reason the turtle could not move.
 function down() end
+
+--- Rotate the turtle 90 degress to the left.
 function turnLeft() end
+
+--- Rotate the turtle 90 degress to the right.
 function turnRight() end
+
+--- Attempt to break the block in front of the turtle.
+--
+-- This requires a turtle tool capable of breaking the block. Diamond pickaxes
+-- (mining turtles) can break any vanilla block, but other tools (such as axes)
+-- are more limited.
+--
+-- @tparam[opt] "left"|"right" side The specific tool to use.
+-- @treturn boolean Whether a block was broken.
+-- @treturn string|nil The reason no block was broken.
 function dig(side) end
+
+--- Attempt to break the block above the turtle. See @{dig} for full details.
+--
+-- @tparam[opt] "left"|"right" side The specific tool to use.
+-- @treturn boolean Whether a block was broken.
+-- @treturn string|nil The reason no block was broken.
 function digUp(side) end
+
+--- Attempt to break the block below the turtle. See @{dig} for full details.
+--
+-- @tparam[opt] "left"|"right" side The specific tool to use.
+-- @treturn boolean Whether a block was broken.
+-- @treturn string|nil The reason no block was broken.
 function digDown(side) end
+
+--- Attack the entity in front of the turtle.
+--
+-- @tparam[opt] "left"|"right" side The specific tool to use.
+-- @treturn boolean Whether an entity was attacked.
+-- @treturn string|nil The reason nothing was attacked.
+function attack(side) end
+
+--- Attack the entity above the turtle.
+--
+-- @tparam[opt] "left"|"right" side The specific tool to use.
+-- @treturn boolean Whether an entity was attacked.
+-- @treturn string|nil The reason nothing was attacked.
+function attackUp(side) end
+
+--- Attack the entity below the turtle.
+--
+-- @tparam[opt] "left"|"right" side The specific tool to use.
+-- @treturn boolean Whether an entity was attacked.
+-- @treturn string|nil The reason nothing was attacked.
+function attackDown(side) end
+
+--- Place a block or item into the world in front of the turtle.
+--
+-- @treturn boolean Whether the block could be placed.
+-- @treturn string|nil The reason the block was not placed.
 function place() end
+
+--- Place a block or item into the world above the turtle.
+--
+-- @treturn boolean Whether the block could be placed.
+-- @treturn string|nil The reason the block was not placed.
 function placeUp() end
+
+--- Place a block or item into the world below the turtle.
+--
+-- @treturn boolean Whether the block could be placed.
+-- @treturn string|nil The reason the block was not placed.
 function placeDown() end
+
+--- Drop the currently selected stack into the inventory in front of the turtle,
+-- or as an item into the world if there is no inventory.
+--
+-- @tparam[opt] number count The number of items to drop. If not given, the
+-- entire stack will be dropped.
+-- @treturn boolean Whether items were dropped.
+-- @treturn string|nil The reason the no items were dropped.
+-- @see select
 function drop(count) end
-function select(slot) end
+
-function getItemCount(slot) end
+--- Drop the currently selected stack into the inventory above the turtle, or as
-function getItemSpace(slot) end
+-- an item into the world if there is no inventory.
+--
+-- @tparam[opt] number count The number of items to drop. If not given, the
+-- entire stack will be dropped.
+-- @treturn boolean Whether items were dropped.
+-- @treturn string|nil The reason the no items were dropped.
+-- @see select
+function dropUp(count) end
+
+--- Drop the currently selected stack into the inventory below the turtle, or as
+-- an item into the world if there is no inventory.
+--
+-- @tparam[opt] number count The number of items to drop. If not given, the
+-- entire stack will be dropped.
+-- @treturn boolean Whether items were dropped.
+-- @treturn string|nil The reason the no items were dropped.
+-- @see select
+function dropDown(count) end
+
+--- Suck an item from the inventory in front of the turtle, or from an item
+-- floating in the world.
+--
+-- This will pull items into the first acceptable slot, starting at the
+-- @{select|currently selected} one.
+--
+-- @tparam[opt] number count The number of items to suck. If not given, up to a
+-- stack of items will be picked up.
+-- @treturn boolean Whether items were picked up.
+-- @treturn string|nil The reason the no items were picked up.
+function suck(count) end
+
+--- Suck an item from the inventory above the turtle, or from an item floating
+-- in the world.
+--
+-- @tparam[opt] number count The number of items to suck. If not given, up to a
+-- stack of items will be picked up.
+-- @treturn boolean Whether items were picked up.
+-- @treturn string|nil The reason the no items were picked up.
+function suckUp(count) end
+
+--- Suck an item from the inventory below the turtle, or from an item floating
+-- in the world.
+--
+-- @tparam[opt] number count The number of items to suck. If not given, up to a
+-- stack of items will be picked up.
+-- @treturn boolean Whether items were picked up.
+-- @treturn string|nil The reason the no items were picked up.
+function suckDown(count) end
+
+--- Check if there is a solid block in front of the turtle. In this case, solid
+-- refers to any non-air or liquid block.
+--
+-- @treturn boolean If there is a solid block in front.
 function detect() end
+
+--- Check if there is a solid block above the turtle.
+--
+-- @treturn boolean If there is a solid block above.
 function detectUp() end
+
+--- Check if there is a solid block below the turtle.
+--
+-- @treturn boolean If there is a solid block below.
 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
+
+
+--- Change the currently selected slot.
+--
+-- The selected slot is determines what slot actions like @{drop} or
+-- @{getItemCount} act on.
+--
+-- @tparam number slot The slot to select.
+-- @see getSelectedSlot
+function select(slot) end
+
+--- Get the currently selected slot.
+--
+-- @treturn number The current slot.
+-- @see select
+function getSelectedSlot() end
+
+--- Get the number of items in the given slot.
+--
+-- @tparam[opt] number slot The slot we wish to check. Defaults to the @{turtle.select|selected slot}.
+-- @treturn number The number of items in this slot.
+function getItemCount(slot) end
+
+--- Get the remaining number of items which may be stored in this stack.
+--
+-- For instance, if a slot contains 13 blocks of dirt, it has room for another 51.
+--
+-- @tparam[opt] number slot The slot we wish to check. Defaults to the @{turtle.select|selected slot}.
+-- @treturn number The space left in this slot.
+function getItemSpace(slot) end
+
+
+--- Get detailed information about the items in the given slot.
+--
+-- @tparam[opt] number slot The slot to get information about. Defaults to the @{turtle.select|selected slot}.
+-- @treturn nil|table Information about the given slot, or @{nil} if it is empty.
+-- @usage Print the current slot, assuming it contains 13 dirt.
+--
+--     print(textutils.serialize(turtle.getItemDetail()))
+--     -- => {
+--     --    name = "minecraft:dirt",
+--     --    damage = 0,
+--     --    count = 13,
+--     -- }
 function getItemDetail(slot) end
+
+function getFuelLevel() end
+
+function refuel(count) end
+function compareTo(slot) end
+function transferTo(slot, count) end
+
+function getFuelLimit() end
+function equipLeft() end
+function equipRight() end
+
+function craft(limit) end

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

@@ -105,14 +105,16 @@ function getMethods(name)
     return nil
 end
 
---- Call a method on a peripheral with a given name
+--- Call a method on the peripheral with the given name.
 --
 -- @tparam string name 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.
 --
--- @usage peripheral.call("top", "open", 1)
+-- @usage Open the modem on the top of this computer.
+--
+--     peripheral.call("top", "open", 1)
 function call(name, method, ...)
     expect(1, name, "string")
     expect(2, method, "string")

src/main/resources/assets/computercraft/lua/rom/apis/turtle/turtle.lua

@@ -5,7 +5,7 @@
 if not turtle then
     error("Cannot load turtle API on computer", 2)
 end
-native = turtle.native or turtle
+native = turtle.native or turtle --- @local
 
 local function addCraftMethod(object)
     if peripheral.getType("left") == "workbench" then

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

@@ -229,9 +229,11 @@ function create(parent, nX, nY, nWidth, nHeight, bStartVisible)
         end
     end
 
-    --- Terminal implementation
+    --- The window object. Refer to the @{window|module's documentation} for
+    -- a full description.
     --
     -- @type Window
+    -- @see term.Redirect
     local window = {}
 
     function window.write(sText)
@@ -437,6 +439,13 @@ function create(parent, nX, nY, nWidth, nHeight, bStartVisible)
         return nBackgroundColor
     end
 
+    --- Get the buffered contents of a line in this window.
+    ---
+    -- @tparam number y The y position of the line to get.
+    -- @treturn string The textual content of this line.
+    -- @treturn string The text colours of this line, suitable for use with @{term.blit}.
+    -- @treturn string The background colours of this line, suitable for use with @{term.blit}.
+    -- @throws If `y` is a valid line.
     function window.getLine(y)
         if type(y) ~= "number" then expect(1, y, "number") end
 
@@ -448,16 +457,26 @@ function create(parent, nX, nY, nWidth, nHeight, bStartVisible)
     end
 
     -- Other functions
-    function window.setVisible(bVis)
+
-        if type(bVis) ~= "boolean" then expect(1, bVis, "boolean") end
+    --- Set whether this window is visible. Invisible windows will not be drawn
-        if bVisible ~= bVis then
+    -- to the screen until they are made visible again.
-            bVisible = bVis
+    --
+    -- Making an invisible window visible will immediately draw it.
+    --
+    -- @tparam boolean visible Whether this window is visible.
+    function window.setVisible(visible)
+        if type(visible) ~= "boolean" then expect(1, visible, "boolean") end
+        if bVisible ~= visible then
+            bVisible = visible
             if bVisible then
                 window.redraw()
             end
         end
     end
 
+    --- Draw this window. This does nothing if the window is not visible.
+    --
+    -- @see Window:setVisible
     function window.redraw()
         if bVisible then
             redraw()
@@ -468,6 +487,8 @@ function create(parent, nX, nY, nWidth, nHeight, bStartVisible)
         end
     end
 
+    --- Set the current terminal's cursor to where this window's cursor is. This
+    -- does nothing if the window is not visible.
     function window.restoreCursor()
         if bVisible then
             updateCursorBlink()
@@ -476,31 +497,47 @@ function create(parent, nX, nY, nWidth, nHeight, bStartVisible)
         end
     end
 
+    --- Get the position of the top left corner of this window.
+    --
+    -- @treturn number The x position of this window.
+    -- @treturn number The y position of this window.
     function window.getPosition()
         return nX, nY
     end
 
-    function window.reposition(nNewX, nNewY, nNewWidth, nNewHeight, newParent)
+    --- Reposition or resize the given window.
-        if type(nNewX) ~= "number" then expect(1, nNewX, "number") end
+    --
-        if type(nNewY) ~= "number" then expect(2, nNewY, "number") end
+    -- This function also accepts arguments to change the size of this window.
-        if nNewWidth ~= nil or nNewHeight ~= nil then
+    -- It is recommended that you fire a `term_resize` event after changing a
-            expect(3, nNewWidth, "number")
+    -- window's, to allow programs to adjust their sizing.
-            expect(4, nNewHeight, "number")
+    --
+    -- @tparam number new_x The new x position of this window.
+    -- @tparam number new_y The new y position of this window.
+    -- @tparam[opt] number new_width The new width of this window.
+    -- @tparam number new_height The new height of this window.
+    -- @tparam[opt] term.Redirect new_parent The new redirect object this
+    -- window should draw to.
+    function window.reposition(new_x, new_y, new_width, new_height, new_parent)
+        if type(new_x) ~= "number" then expect(1, new_x, "number") end
+        if type(new_y) ~= "number" then expect(2, new_y, "number") end
+        if new_width ~= nil or new_height ~= nil then
+            expect(3, new_width, "number")
+            expect(4, new_height, "number")
         end
-        if newParent ~= nil and type(newParent) ~= "table" then expect(5, newParent, "table") end
+        if new_parent ~= nil and type(new_parent) ~= "table" then expect(5, new_parent, "table") end
 
-        nX = nNewX
+        nX = new_x
-        nY = nNewY
+        nY = new_y
 
-        if newParent then parent = newParent end
+        if new_parent then parent = new_parent end
 
-        if nNewWidth and nNewHeight then
+        if new_width and new_height then
             local tNewLines = {}
-            createEmptyLines(nNewWidth)
+            createEmptyLines(new_width)
             local sEmptyText = sEmptySpaceLine
             local sEmptyTextColor = tEmptyColorLines[nTextColor]
             local sEmptyBackgroundColor = tEmptyColorLines[nBackgroundColor]
-            for y = 1, nNewHeight do
+            for y = 1, new_height do
                 if y > nHeight then
                     tNewLines[y] = {
                         text = sEmptyText,
@@ -509,25 +546,25 @@ function create(parent, nX, nY, nWidth, nHeight, bStartVisible)
                     }
                 else
                     local tOldLine = tLines[y]
-                    if nNewWidth == nWidth then
+                    if new_width == nWidth then
                         tNewLines[y] = tOldLine
-                    elseif nNewWidth < nWidth then
+                    elseif new_width < nWidth then
                         tNewLines[y] = {
-                            text = string_sub(tOldLine.text, 1, nNewWidth),
+                            text = string_sub(tOldLine.text, 1, new_width),
-                            textColor = string_sub(tOldLine.textColor, 1, nNewWidth),
+                            textColor = string_sub(tOldLine.textColor, 1, new_width),
-                            backgroundColor = string_sub(tOldLine.backgroundColor, 1, nNewWidth),
+                            backgroundColor = string_sub(tOldLine.backgroundColor, 1, new_width),
                         }
                     else
                         tNewLines[y] = {
-                            text = tOldLine.text .. string_sub(sEmptyText, nWidth + 1, nNewWidth),
+                            text = tOldLine.text .. string_sub(sEmptyText, nWidth + 1, new_width),
-                            textColor = tOldLine.textColor .. string_sub(sEmptyTextColor, nWidth + 1, nNewWidth),
+                            textColor = tOldLine.textColor .. string_sub(sEmptyTextColor, nWidth + 1, new_width),
-                            backgroundColor = tOldLine.backgroundColor .. string_sub(sEmptyBackgroundColor, nWidth + 1, nNewWidth),
+                            backgroundColor = tOldLine.backgroundColor .. string_sub(sEmptyBackgroundColor, nWidth + 1, new_width),
                         }
                     end
                 end
             end
-            nWidth = nNewWidth
+            nWidth = new_width
-            nHeight = nNewHeight
+            nHeight = new_height
             tLines = tNewLines
         end
         if bVisible then