Clean up some examples a little bit

Would be good if they didn't crash and burn on entry :).

doc/stub/fs.lua

@@ -15,7 +15,7 @@
 function isDriveRoot(path) end
 
 --[[- Provides completion for a file or directory name, suitable for use with
-@{read}.
+@{_G.read}.
 
 When a directory is a possible candidate for completion, two entries are
 included - one with a trailing slash (indicating that entries within this

doc/stub/os.lua

@@ -85,6 +85,9 @@ the `terminate` event yourself - the program will not stop execution when
 function pullEventRaw(filter) end
 
 --- Pauses execution for the specified number of seconds, alias of @{_G.sleep}.
+--
+-- @tparam number time The number of seconds to sleep for, rounded up to the
+-- nearest multiple of 0.05.
 function sleep(time) end
 
 --- Get the current CraftOS version (for example, `CraftOS 1.8`).
@@ -93,6 +96,7 @@ function sleep(time) end
 -- should return `CraftOS 1.8`.
 --
 -- @treturn string The current CraftOS version.
+-- @usage os.version()
 function version() end
 
 --[[- Run the program at the given path with the specified environment and
@@ -113,7 +117,7 @@ such as @{loadfile}.
 @treturn boolean Whether or not the program ran successfully.
 @usage Run the default shell from within your program:
 
-    os.run({}, "/rom/programs/shell")
+    os.run({}, "/rom/programs/shell.lua")
 
 @see shell.run
 @see loadfile

illuaminate.sexp

@@ -97,15 +97,6 @@
 
   (linters -doc:undocumented -doc:undocumented-arg -doc:undocumented-return))
 
-;; These currently rely on unknown references.
-(at
-  (/src/main/resources/*/computercraft/lua/rom/apis/textutils.lua
-   /src/main/resources/*/computercraft/lua/rom/modules/main/cc/completion.lua
-   /src/main/resources/*/computercraft/lua/rom/modules/main/cc/shell/completion.lua
-   /src/main/resources/*/computercraft/lua/rom/programs/shell.lua
-   /doc/stub/fs.lua)
-  (linters -doc:unresolved-reference))
-
 ;; Suppress warnings for the BIOS using its own deprecated members for now.
 (at /src/main/resources/*/computercraft/lua/bios.lua
   (linters -var:deprecated))

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

@@ -270,7 +270,7 @@ end
 -- @treturn number The combined hexadecimal colour.
 -- @usage
 -- ```lua
--- colors.rgb(0.7, 0.2, 0.6)
+-- colors.packRGB(0.7, 0.2, 0.6)
 -- -- => 0xb23399
 -- ```
 function packRGB(r, g, b)
@@ -291,7 +291,7 @@ end
 -- @treturn number The blue channel, will be between 0 and 1.
 -- @usage
 -- ```lua
--- colors.rgb(0xb23399)
+-- colors.unpackRGB(0xb23399)
 -- -- => 0.7, 0.2, 0.6
 -- ```
 -- @see colors.packRGB
@@ -317,12 +317,12 @@ end
 -- @deprecated Use @{packRGB} or @{unpackRGB} directly.
 -- @usage
 -- ```lua
--- colors.rgb(0xb23399)
+-- colors.rgb8(0xb23399)
 -- -- => 0.7, 0.2, 0.6
 -- ```
 -- @usage
 -- ```lua
--- colors.rgb(0.7, 0.2, 0.6)
+-- colors.rgb8(0.7, 0.2, 0.6)
 -- -- => 0xb23399
 -- ```
 function rgb8(r, g, b)

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

@@ -22,7 +22,7 @@ end
 --
 -- @tparam string name The name of the disk drive.
 -- @treturn boolean If something is in the disk drive.
--- @usage disk.isPresent(false)
+-- @usage disk.isPresent("top")
 function isPresent(name)
     if isDrive(name) then
         return peripheral.call(name, "isDiskPresent")

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

@@ -32,7 +32,7 @@ end
 -- @tparam string topic The topic to find
 -- @treturn string|nil The path to the given topic's help file, or `nil` if it
 -- cannot be found.
--- @usage print(help.lookup("disk"))
+-- @usage help.lookup("disk")
 function lookup(_sTopic)
     expect(1, _sTopic, "string")
     -- Look on the path variable
@@ -52,6 +52,7 @@ end
 --- Returns a list of topics that can be looked up and/or displayed.
 --
 -- @treturn table A list of topics in alphabetical order.
+-- @usage help.topics()
 function topics()
     -- Add index
     local tItems = {

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

@@ -145,6 +145,7 @@ keys.cimcumflex = keys.circumflex --- @local
 --
 -- @tparam number code The key code to look up.
 -- @treturn string|nil The name of the key, or `nil` if not a valid key code.
+-- @usage keys.getName(keys.enter)
 function getName(_nKey)
     expect(1, _nKey, "number")
     return tKeys[_nKey]

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

@@ -191,7 +191,7 @@ end
 -- filter function, which takes the peripheral's name and wrapped table
 -- and returns if it should be included in the result.
 -- @treturn table... 0 or more wrapped peripherals matching the given filters.
--- @usage local monitors = { peripheral.find("monitor") }
+-- @usage { peripheral.find("monitor") }
 -- @usage peripheral.find("modem", rednet.open)
 function find(ty, filter)
     expect(1, ty, "string")

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

@@ -9,7 +9,7 @@ local expect, field = expect.expect, expect.field
 --- Slowly writes string text at current cursor position,
 -- character-by-character.
 --
--- Like @{write}, this does not insert a newline at the end.
+-- Like @{_G.write}, this does not insert a newline at the end.
 --
 -- @tparam string sText The the text to write to the screen
 -- @tparam[opt] number nRate The number of characters to write each second,
@@ -119,8 +119,8 @@ end
 -- displayed before prompting.
 -- @treturn number The number of lines printed.
 -- @usage
--- local width, height = term.getSize()
--- textutils.pagedPrint(("This is a rather verbose dose of repetition.\n"):rep(30), height - 2)
+--     local width, height = term.getSize()
+--     textutils.pagedPrint(("This is a rather verbose dose of repetition.\n"):rep(30), height - 2)
 function pagedPrint(_sText, _nFreeLines)
     expect(2, _nFreeLines, "number", "nil")
     -- Setup a redirector
@@ -706,7 +706,7 @@ unserialiseJSON = unserialise_json
 --
 -- @tparam string str The string to encode
 -- @treturn string The encoded string.
--- @usage print("https://example.com/?view=" .. textutils.urlEncode(read()))
+-- @usage print("https://example.com/?view=" .. textutils.urlEncode("some text&things"))
 function urlEncode(str)
     expect(1, str, "string")
     if str then
@@ -744,8 +744,8 @@ local tEmpty = {}
 --
 -- @treturn { string... } The (possibly empty) list of completions.
 -- @see shell.setCompletionFunction
--- @see read
--- @usage textutils.complete( "pa", getfenv() )
+-- @see _G.read
+-- @usage textutils.complete( "pa", _ENV )
 function complete(sSearchText, tSearchTable)
     expect(1, sSearchText, "string")
     expect(2, tSearchTable, "table", "nil")

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

@@ -1,5 +1,5 @@
 --- A collection of helper methods for working with input completion, such
--- as that require by @{read}.
+-- as that require by @{_G.read}.
 --
 -- @module cc.completion
 -- @see cc.shell.completion For additional helpers to use with
@@ -29,7 +29,7 @@ end
 -- @tparam { string... } choices The list of choices to complete from.
 -- @tparam[opt] boolean add_space Whether to add a space after the completed item.
 -- @treturn { string... } A list of suffixes of matching strings.
--- @usage Call @{read}, completing the names of various animals.
+-- @usage Call @{_G.read}, completing the names of various animals.
 --
 --     local animals = { "dog", "cat", "lion", "unicorn" }
 --     read(nil, nil, function(text) return choice(text, animals) end)

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

@@ -13,11 +13,11 @@
 -- @module cc.pretty
 -- @usage Print a table to the terminal
 --     local pretty = require "cc.pretty"
---     pretty.write(pretty.pretty({ 1, 2, 3 }))
+--     pretty.print(pretty.pretty({ 1, 2, 3 }))
 --
 -- @usage Build a custom document and display it
 --     local pretty = require "cc.pretty"
---     pretty.write(pretty.group(pretty.text("hello") .. pretty.space_line .. pretty.text("world")))
+--     pretty.print(pretty.group(pretty.text("hello") .. pretty.space_line .. pretty.text("world")))
 
 local expect = require "cc.expect"
 local expect, field = expect.expect, expect.field

src/main/resources/data/computercraft/lua/rom/modules/main/cc/shell/completion.lua

@@ -8,7 +8,7 @@
 -- wrap them using @{build}, or your own custom function.
 --
 -- @module cc.shell.completion
--- @see cc.completion For more general helpers, suitable for use with @{read}.
+-- @see cc.completion For more general helpers, suitable for use with @{_G.read}.
 -- @see shell.setCompletionFunction
 
 local expect = require "cc.expect".expect

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

@@ -383,7 +383,7 @@ end
 --
 -- @tparam string sLine The input to complete.
 -- @treturn { string }|nil The list of possible completions.
--- @see read For more information about completion.
+-- @see _G.read For more information about completion.
 -- @see shell.completeProgram
 -- @see shell.setCompletionFunction
 -- @see shell.getCompletionInfo
@@ -461,7 +461,7 @@ end
 -- The completion function.
 -- @see cc.shell.completion Various utilities to help with writing completion functions.
 -- @see shell.complete
--- @see read For more information about completion.
+-- @see _G.read For more information about completion.
 function shell.setCompletionFunction(program, complete)
     expect(1, program, "string")
     expect(2, complete, "function")