Cleanup examples for the various modules

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

@@ -31,8 +31,9 @@ end
 -- @treturn { string... } A list of suffixes of matching strings.
 -- @usage Call @{_G.read}, completing the names of various animals.
 --
+--     local completion = require "cc.completion"
 --     local animals = { "dog", "cat", "lion", "unicorn" }
---     read(nil, nil, function(text) return choice(text, animals) end)
+--     read(nil, nil, function(text) return completion.choice(text, animals) end)
 local function choice(text, choices, add_space)
     expect(1, text, "string")
     expect(2, choices, "table")
@@ -45,7 +46,9 @@ end
 -- @tparam string text The input string to complete.
 -- @tparam[opt] boolean add_space Whether to add a space after the completed name.
 -- @treturn { string... } A list of suffixes of matching peripherals.
--- @usage read(nil, nil, peripheral)
+-- @usage <!-- -->
+--     local completion = require "cc.completion"
+--     read(nil, nil, completion.peripheral)
 local function peripheral_(text, add_space)
     expect(1, text, "string")
     expect(2, add_space, "boolean", "nil")
@@ -59,7 +62,9 @@ local sides = redstone.getSides()
 -- @tparam string text The input string to complete.
 -- @tparam[opt] boolean add_space Whether to add a space after the completed side.
 -- @treturn { string... } A list of suffixes of matching sides.
--- @usage read(nil, nil, side)
+-- @usage <!-- -->
+--     local completion = require "cc.completion"
+--     read(nil, nil, completion.side)
 local function side(text, add_space)
     expect(1, text, "string")
     expect(2, add_space, "boolean", "nil")
@@ -71,7 +76,9 @@ end
 -- @tparam string text The input string to complete.
 -- @tparam[opt] boolean add_space Whether to add a space after the completed settings.
 -- @treturn { string... } A list of suffixes of matching settings.
--- @usage read(nil, nil, setting)
+-- @usage <!-- -->
+--     local completion = require "cc.completion"
+--     read(nil, nil, completion.setting)
 local function setting(text, add_space)
     expect(1, text, "string")
     expect(2, add_space, "boolean", "nil")
@@ -85,7 +92,9 @@ local command_list
 -- @tparam string text The input string to complete.
 -- @tparam[opt] boolean add_space Whether to add a space after the completed command.
 -- @treturn { string... } A list of suffixes of matching commands.
--- @usage read(nil, nil, command)
+-- @usage <!-- -->
+--     local completion = require "cc.completion"
+--     read(nil, nil, completion.command)
 local function command(text, add_space)
     expect(1, text, "string")
     expect(2, add_space, "boolean", "nil")

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

@@ -1,7 +1,26 @@
---- The @{cc.expect} library provides helper functions for verifying that
--- function arguments are well-formed and of the correct type.
---
--- @module cc.expect
+--[[- The @{cc.expect} library provides helper functions for verifying that
+function arguments are well-formed and of the correct type.
+
+@module cc.expect
+@usage Define a basic function and check it has the correct arguments.
+
+    local expect = require "cc.expect"
+    local expect, field = expect.expect, expect.field
+
+    local function add_person(name, info)
+        expect(1, name, "string")
+        expect(2, info, "table", "nil")
+
+        if info then
+            print("Got age=", field(info, "age", "number"))
+            print("Got gender=", field(info, "gender", "string", "nil"))
+        end
+    end
+
+    add_person("Anastazja") -- `info' is optional
+    add_person("Kion", { age = 23 }) -- `gender' is optional
+    add_person("Caoimhin", { age = 23, gender = true }) -- error!
+]]
 
 local native_select, native_type = select, type
 

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

@@ -67,6 +67,9 @@ end
 -- @tparam[opt] number colour The colour this text should be printed with. If not given, we default to the current
 -- colour.
 -- @treturn Doc The document with the provided text.
+-- @usage Write some blue text.
+--     local pretty = require "cc.pretty"
+--     pretty.print(pretty.text("Hello!", colours.blue))
 local function text(text, colour)
     expect(1, text, "string")
     expect(2, colour, "number", "nil")
@@ -101,8 +104,11 @@ end
 --
 -- @tparam Doc|string ... The documents to concatenate.
 -- @treturn Doc The concatenated documents.
--- @usage pretty.concat(doc1, " - ", doc2)
--- @usage doc1 .. " - " .. doc2
+-- @usage <!-- -->
+--     local pretty = require "cc.pretty"
+--     local doc1, doc2 = pretty.text("doc1"), pretty.text("doc2")
+--     print(pretty.concat(doc1, " - ", doc2))
+--     print(doc1 .. " - " .. doc2) -- Also supports ..
 local function concat(...)
     local args = table.pack(...)
     for i = 1, args.n do
@@ -135,7 +141,9 @@ Doc.__concat = concat --- @local
 -- @tparam number depth The number of spaces with which the document should be indented.
 -- @tparam Doc    doc   The document to indent.
 -- @treturn Doc The nested document.
--- @usage pretty.nest(2, pretty.text("foo\nbar"))
+-- @usage <!-- -->
+--     local pretty = require "cc.pretty"
+--     print(pretty.nest(2, pretty.text("foo\nbar")))
 local function nest(depth, doc)
     expect(1, depth, "number")
     if getmetatable(doc) ~= Doc then expect(2, doc, "document") end
@@ -169,6 +177,12 @@ end
 --
 -- @tparam Doc doc The document to group.
 -- @treturn Doc The grouped document.
+-- @usage Uses group to show things being displayed on one or multiple lines.
+--
+--     local pretty = require "cc.pretty"
+--     local doc = pretty.group("Hello" .. pretty.space_line .. "World")
+--     print(pretty.render(doc, 5)) -- On multiple lines
+--     print(pretty.render(doc, 20)) -- Collapsed onto one.
 local function group(doc)
     if getmetatable(doc) ~= Doc then expect(1, doc, "document") end
 

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

@@ -9,9 +9,13 @@
 -- @usage Construct the package and require function, and insert them into a
 -- custom environment.
 --
---     local env = setmetatable({}, { __index = _ENV })
 --     local r = require "cc.require"
+--     local env = setmetatable({}, { __index = _ENV })
 --     env.require, env.package = r.make(env, "/")
+--
+--     -- Now we have our own require function, separate to the original.
+--     local r2 = env.require "cc.require"
+--     print(r, r2)
 
 local expect = require and require("cc.expect") or dofile("rom/modules/main/cc/expect.lua")
 local expect = expect.expect

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

@@ -1,15 +1,28 @@
---- A collection of helper methods for working with shell completion.
---
--- Most programs may be completed using the @{build} helper method, rather than
--- manually switching on the argument index.
---
--- Note, the helper functions within this module do not accept an argument index,
--- and so are not directly usable with the @{shell.setCompletionFunction}. Instead,
--- wrap them using @{build}, or your own custom function.
---
--- @module cc.shell.completion
--- @see cc.completion For more general helpers, suitable for use with @{_G.read}.
--- @see shell.setCompletionFunction
+--[[- A collection of helper methods for working with shell completion.
+
+Most programs may be completed using the @{build} helper method, rather than
+manually switching on the argument index.
+
+Note, the helper functions within this module do not accept an argument index,
+and so are not directly usable with the @{shell.setCompletionFunction}. Instead,
+wrap them using @{build}, or your own custom function.
+
+@module cc.shell.completion
+@see cc.completion For more general helpers, suitable for use with @{_G.read}.
+@see shell.setCompletionFunction
+
+@usage Register a completion handler for example.lua which prompts for a
+choice of options, followed by a directory, and then multiple files.
+
+    local completion = require "cc.shell.completion"
+    local complete = completion.build(
+      { completion.choice, { "get", "put" } },
+      completion.dir,
+      { completion.file, many = true }
+    )
+    shell.setCompletionFunction("example.lua", complete)
+    read(nil, nil, shell.complete, "example ")
+]]
 
 local expect = require "cc.expect".expect
 local completion = require "cc.completion"
@@ -69,37 +82,29 @@ local function program(shell, text)
     return shell.completeProgram(text)
 end
 
---- A helper function for building shell completion arguments.
---
--- This accepts a series of single-argument completion functions, and combines
--- them into a function suitable for use with @{shell.setCompletionFunction}.
---
--- @tparam nil|table|function ... Every argument to @{build} represents an argument
--- to the program you wish to complete. Each argument can be one of three types:
---
---  - `nil`: This argument will not be completed.
---
---  - A function: This argument will be completed with the given function. It is
---    called with the @{shell} object, the string to complete and the arguments
---    before this one.
---
---  - A table: This acts as a more powerful version of the function case. The table
---    must have a function as the first item - this will be called with the shell,
---    string and preceding arguments as above, but also followed by any additional
---    items in the table. This provides a more convenient interface to pass
---    options to your completion functions.
---
---    If this table is the last argument, it may also set the `many` key to true,
---    which states this function should be used to complete any remaining arguments.
---
--- @usage Prompt for a choice of options, followed by a directory, and then multiple
--- files.
---
---     complete.build(
---       { complete.choice, { "get", "put" } },
---       complete.dir,
---       { complete.file, many = true }
---     )
+--[[- A helper function for building shell completion arguments.
+
+This accepts a series of single-argument completion functions, and combines
+them into a function suitable for use with @{shell.setCompletionFunction}.
+
+@tparam nil|table|function ... Every argument to @{build} represents an argument
+to the program you wish to complete. Each argument can be one of three types:
+
+ - `nil`: This argument will not be completed.
+
+ - A function: This argument will be completed with the given function. It is
+   called with the @{shell} object, the string to complete and the arguments
+   before this one.
+
+ - A table: This acts as a more powerful version of the function case. The table
+   must have a function as the first item - this will be called with the shell,
+   string and preceding arguments as above, but also followed by any additional
+   items in the table. This provides a more convenient interface to pass
+   options to your completion functions.
+
+   If this table is the last argument, it may also set the `many` key to true,
+   which states this function should be used to complete any remaining arguments.
+]]
 local function build(...)
     local arguments = table.pack(...)
     for i = 1, arguments.n do