Write an introduction to the turtle API

It's better at least, I just don't know if it's good.

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

@@ -22,7 +22,7 @@
  * as those from Project:Red. These allow you to send 16 separate on/off signals. Each channel corresponds to a
  * colour, with the first being @{colors.white} and the last @{colors.black}.
  *
- * Whenever a redstone input changes, a {@code redstone} event will be fired. This may be used instead of repeativly
+ * Whenever a redstone input changes, a @{event!redstone} event will be fired. This may be used instead of repeativly
  * polling.
  *
  * This module may also be referred to as {@code rs}. For example, one may call {@code rs.getSides()} instead of

src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java

@@ -25,10 +25,9 @@
 import java.util.Optional;
 
 /**
- * The turtle API allows you to control your turtle.
+ * Doc stub. Exists in turtle.lua instead.
  *
  * @cc.module turtle
- * @cc.since 1.3
  */
 public class TurtleAPI implements ILuaAPI
 {

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

@@ -2,13 +2,13 @@
 
 Functions are not actually executed simultaniously, but rather this API will
 automatically switch between them whenever they yield (eg whenever they call
-@{coroutine.yield}, or functions that call that - eg `os.pullEvent` - or
+@{coroutine.yield}, or functions that call that - eg @{os.pullEvent} - or
 functions that call that, etc - basically, anything that causes the function
 to "pause").
 
 Each function executed in "parallel" gets its own copy of the event queue,
 and so "event consuming" functions (again, mostly anything that causes the
-script to pause - eg `sleep`, `rednet.receive`, most of the `turtle` API,
+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.
 

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

@@ -108,39 +108,48 @@ local function makePagedScroll(_term, _nFreeLines)
     end
 end
 
---- Prints a given string to the display.
+--[[- Prints a given string to the display.
---
+
--- If the action can be completed without scrolling, it acts much the same as
+If the action can be completed without scrolling, it acts much the same as
--- @{print}; otherwise, it will throw up a "Press any key to continue" prompt at
+@{print}; otherwise, it will throw up a "Press any key to continue" prompt at
--- the bottom of the display. Each press will cause it to scroll down and write
+the bottom of the display. Each press will cause it to scroll down and write a
--- a single line more before prompting again, if need be.
+single line more before prompting again, if need be.
---
+
--- @tparam string _sText The text to print to the screen.
+@tparam string text The text to print to the screen.
--- @tparam[opt] number _nFreeLines The number of lines which will be
+@tparam[opt] number free_lines The number of lines which will be
--- automatically scrolled before the first prompt appears (meaning _nFreeLines +
+automatically scrolled before the first prompt appears (meaning free_lines +
--- 1 lines will be printed). This can be set to the terminal's height - 2 to
+1 lines will be printed). This can be set to the cursor's y position - 2 to
--- always try to fill the screen. Defaults to 0, meaning only one line is
+always try to fill the screen. Defaults to 0, meaning only one line is
--- displayed before prompting.
+displayed before prompting.
--- @treturn number The number of lines printed.
+@treturn number The number of lines printed.
--- @usage
+
---     local width, height = term.getSize()
+@usage Generates several lines of text and then prints it, paging once the
---     textutils.pagedPrint(("This is a rather verbose dose of repetition.\n"):rep(30), height - 2)
+bottom of the terminal is reached.
-function pagedPrint(_sText, _nFreeLines)
+
-    expect(2, _nFreeLines, "number", "nil")
+    local lines = {}
+    for i = 1, 30 do lines[i] = ("This is line #%d"):format(i) end
+    local message = table.concat(lines, "\n")
+
+    local width, height = term.getCursorPos()
+    textutils.pagedPrint(message, height - 2)
+]]
+function pagedPrint(text, free_lines)
+    expect(2, free_lines, "number", "nil")
     -- Setup a redirector
     local oldTerm = term.current()
     local newTerm = {}
     for k, v in pairs(oldTerm) do
         newTerm[k] = v
     end
-    newTerm.scroll = makePagedScroll(oldTerm, _nFreeLines)
+
+    newTerm.scroll = makePagedScroll(oldTerm, free_lines)
     term.redirect(newTerm)
 
     -- Print the text
     local result
     local ok, err = pcall(function()
-        if _sText ~= nil then
+        if text ~= nil then
-            result = print(_sText)
+            result = print(text)
         else
             result = print()
         end
@@ -214,32 +223,45 @@ local function tabulateCommon(bPaged, ...)
     end
 end
 
---- Prints tables in a structured form.
+--[[- Prints tables in a structured form.
---
+
--- This accepts multiple arguments, either a table or a number. When
+This accepts multiple arguments, either a table or a number. When
--- encountering a table, this will be treated as a table row, with each column
+encountering a table, this will be treated as a table row, with each column
--- width being auto-adjusted.
+width being auto-adjusted.
---
+
--- When encountering a number, this sets the text color of the subsequent rows to it.
+When encountering a number, this sets the text color of the subsequent rows to it.
---
+
--- @tparam {string...}|number ... The rows and text colors to display.
+@tparam {string...}|number ... The rows and text colors to display.
--- @usage textutils.tabulate(colors.orange, { "1", "2", "3" }, colors.lightBlue, { "A", "B", "C" })
+@since 1.3
--- @since 1.3
+@usage
+
+    textutils.tabulate(
+      colors.orange, { "1", "2", "3" },
+      colors.lightBlue, { "A", "B", "C" }
+    )
+]]
 function tabulate(...)
     return tabulateCommon(false, ...)
 end
 
---- Prints tables in a structured form, stopping and prompting for input should
+--[[- Prints tables in a structured form, stopping and prompting for input should
--- the result not fit on the terminal.
+the result not fit on the terminal.
---
+
--- This functions identically to @{textutils.tabulate}, but will prompt for user
+This functions identically to @{textutils.tabulate}, but will prompt for user
--- input should the whole output not fit on the display.
+input should the whole output not fit on the display.
---
+
--- @tparam {string...}|number ... The rows and text colors to display.
+@tparam {string...}|number ... The rows and text colors to display.
--- @usage textutils.tabulate(colors.orange, { "1", "2", "3" }, colors.lightBlue, { "A", "B", "C" })
+@see textutils.tabulate
--- @see textutils.tabulate
+@see textutils.pagedPrint
--- @see textutils.pagedPrint
+@since 1.3
--- @since 1.3
+
+@usage Generates a long table, tabulates it, and prints it to the screen.
+
+    local rows = {}
+    for i = 1, 30 do rows[i] = {("Row #%d"):format(i), math.random(1, 400)} end
+
+    textutils.tabulate(colors.orange, {"Column", "Value"}, colors.lightBlue, table.unpack(rows))
+]]
 function pagedTabulate(...)
     return tabulateCommon(true, ...)
 end
@@ -692,11 +714,11 @@ saving in a file or pretty-printing.
 @throws If the object contains a value which cannot be
 serialised. This includes functions and tables which appear multiple
 times.
-@see cc.pretty.pretty An alternative way to display a table, often more suitable for
+@see cc.pretty.pretty_print An alternative way to display a table, often more
-pretty printing.
+suitable for pretty printing.
 @since 1.3
 @changed 1.97.0 Added `opts` argument.
-@usage Pretty print a basic table.
+@usage Serialise a basic table.
 
     textutils.serialise({ 1, 2, 3, a = 1, ["another key"] = { true } })
 

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

@@ -1,6 +1,51 @@
---- The turtle API allows you to control your turtle.
+--[[- Turtles are a robotic device, which can break and place blocks, attack mobs, and move about the world. They have
---
+an internal inventory of 16 slots, allowing them to store blocks they have broken or would like to place.
--- @module turtle
+
+## Movement
+Turtles are capable of moving throug the world. As turtles are blocks themselves, they are confined to Minecraft's grid,
+moving a single block at a time.
+
+@{turtle.forward} and @{turtle.back} move the turtle in the direction it is facing, while @{turtle.up} and
+@{turtle.down} move it up and down (as one might expect!). In order to move left or right, you first need to turn the
+turtle using @{turtle.turnLeft}/@{turtle.turnRight} and then move forward or backwards.
+
+:::info
+The name "turtle" comes from [Turtle graphics], which originated from the Logo programming language. Here you'd move
+a turtle with various commands like "move 10" and "turn left", much like ComputerCraft's turtles!
+:::
+
+Moving a turtle (though not turning it) consumes *fuel*. If a turtle does not have any @{turtle.refuel|fuel}, it won't
+move, and the movement functions will return @{false}. If your turtle isn't going anywhere, the first thing to check
+is if you've fuelled your turtle.
+
+:::tip Handling errors
+Many turtle functions can fail in various ways. For instance, a turtle cannot move forward if there's already a block
+there. Instead of erroring, functions which can fail either return @{true} if they succeed, or @{false} and some error
+message if they fail.
+
+Unexpected failures can often lead to strange behaviour. It's often a good idea to check the return values of these
+functions, or wrap them in @{assert} (for instance, use `assert(turtle.forward())` rather than `turtle.forward()`),
+so the program doesn't misbehave.
+:::
+
+## Turtle upgrades
+While a normal turtle can move about the world and place blocks, its functionality is limited. Thankfully, turtles can
+be upgraded with *tools* and @{peripheral|peripherals}. Turtles have two upgrade slots, one on the left and right sides.
+Upgrades can be equipped by crafting a turtle with the upgrade, or calling the @{turtle.equipLeft}/@{turtle.equipRight}
+functions.
+
+Turtle tools allow you to break blocks (@{turtle.dig}) and attack entities (@{turtle.attack}). Some tools are more
+suitable to a task than others. For instance, a diamond pickaxe can break every block, while a sword does more damage.
+Other tools have more niche use-cases, for instance hoes can til dirt.
+
+Peripherals (such as the @{modem|wireless modem} or @{speaker}) can also be equipped as upgrades. These are then
+accessible by accessing the `"left"` or `"right"` peripheral.
+
+[Turtle Graphics]: https://en.wikipedia.org/wiki/Turtle_graphics "Turtle graphics"
+
+@module turtle
+@since 1.3
+]]
 
 if not turtle then
     error("Cannot load turtle API on computer", 2)
@@ -8,9 +53,8 @@ end
 
 --- The builtin turtle API, without any generated helper functions.
 --
--- Generally you should not need to use this table - it only exists for
+-- @deprecated Historically this table behaved differently to the main turtle API, but this is no longer the base. You
--- backwards compatibility reasons.
+-- should not need to use it.
--- @deprecated
 native = turtle.native or turtle
 
 local function addCraftMethod(object)

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

@@ -224,8 +224,8 @@ end
 
 --- Display a document on the terminal.
 --
--- @tparam      Doc     doc         The document to render
+-- @tparam          Doc     doc         The document to render
--- @tparam[opt] number  ribbon_frac The maximum fraction of the width that we should write in.
+-- @tparam[opt=0.6] number  ribbon_frac The maximum fraction of the width that we should write in.
 local function write(doc, ribbon_frac)
     if getmetatable(doc) ~= Doc then expect(1, doc, "document") end
     expect(2, ribbon_frac, "number", "nil")
@@ -286,8 +286,8 @@ end
 
 --- Display a document on the terminal with a trailing new line.
 --
--- @tparam      Doc     doc         The document to render.
+-- @tparam          Doc     doc         The document to render.
--- @tparam[opt] number  ribbon_frac The maximum fraction of the width that we should write in.
+-- @tparam[opt=0.6] number  ribbon_frac The maximum fraction of the width that we should write in.
 local function print(doc, ribbon_frac)
     if getmetatable(doc) ~= Doc then expect(1, doc, "document") end
     expect(2, ribbon_frac, "number", "nil")
@@ -297,10 +297,10 @@ end
 
 --- Render a document, converting it into a string.
 --
--- @tparam      Doc     doc         The document to render.
+-- @tparam          Doc     doc         The document to render.
--- @tparam[opt] number  width       The maximum width of this document. Note that long strings will not be wrapped to
+-- @tparam[opt]     number width The maximum width of this document. Note that long strings will not be wrapped to fit
--- fit this width - it is only used for finding the best layout.
+-- this width - it is only used for finding the best layout.
--- @tparam[opt] number  ribbon_frac The maximum fraction of the width that we should write in.
+-- @tparam[opt=0.6] number  ribbon_frac The maximum fraction of the width that we should write in.
 -- @treturn string The rendered document as a string.
 local function render(doc, width, ribbon_frac)
     if getmetatable(doc) ~= Doc then expect(1, doc, "document") end
@@ -483,7 +483,7 @@ Controls how various properties are displayed.
  - `function_args`: Show the arguments to a function if known (`false` by default).
  - `function_source`: Show where the function was defined, instead of
    `function: xxxxxxxx` (`false` by default).
-@tparam[opt] number  ribbon_frac The maximum fraction of the width that we should write in.
+@tparam[opt=0.6] number ribbon_frac The maximum fraction of the width that we should write in.
 
 @usage Display a table on the screen.
 

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

@@ -171,7 +171,7 @@ end
 local current_section = nil
 local offset = 0
 
---- Find the currently visible seciton, or nil if this document has no sections.
+--- Find the currently visible section, or nil if this document has no sections.
 --
 -- This could potentially be a binary search, but right now it's not worth it.
 local function find_section()