Cleanup examples for the various modules

patchwork.md

@@ -335,3 +335,9 @@ Use term.blit on original paint render
 This makes it super speedy, meaning an initial refresh doesn't take ages
 to load.
 ```
+
+```
+b0651082f472baee8f0fa8ec7ba95f433e2637bb
+
+Cleanup examples for the various modules
+```

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

@@ -45,7 +45,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 +61,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 +75,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 +91,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
+--[[- The @{cc.expect} library provides helper functions for verifying that
--- function arguments are well-formed and of the correct type.
+function arguments are well-formed and of the correct type.
---
+
--- @module cc.expect
+@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 <!-- -->
--- @usage doc1 .. " - " .. doc2
+--     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,8 +9,8 @@
 -- @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, "/")
 
 local expect = require and require("cc.expect") or dofile("rom/modules/main/cc/expect.lua")

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.
+--[[- A collection of helper methods for working with shell completion.
---
+
--- Most programs may be completed using the @{build} helper method, rather than
+Most programs may be completed using the @{build} helper method, rather than
--- manually switching on the argument index.
+manually switching on the argument index.
---
+
--- Note, the helper functions within this module do not accept an 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,
+and so are not directly usable with the @{shell.setCompletionFunction}. Instead,
--- wrap them using @{build}, or your own custom function.
+wrap them using @{build}, or your own custom function.
---
+
--- @module cc.shell.completion
+@module cc.shell.completion
--- @see cc.completion For more general helpers, suitable for use with @{_G.read}.
+@see cc.completion For more general helpers, suitable for use with @{_G.read}.
--- @see shell.setCompletionFunction
+@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.
+--[[- A helper function for building shell completion arguments.
---
+
--- This accepts a series of single-argument completion functions, and combines
+This accepts a series of single-argument completion functions, and combines
--- them into a function suitable for use with @{shell.setCompletionFunction}.
+them into a function suitable for use with @{shell.setCompletionFunction}.
---
+
--- @tparam nil|table|function ... Every argument to @{build} represents an argument
+@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:
+to the program you wish to complete. Each argument can be one of three types:
---
+
---  - `nil`: This argument will not be completed.
+ - `nil`: This argument will not be completed.
---
+
---  - A function: This argument will be completed with the given function. It is
+ - 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
+   called with the @{shell} object, the string to complete and the arguments
---    before this one.
+   before this one.
---
+
---  - A table: This acts as a more powerful version of the function case. The table
+ - 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,
+   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
+   string and preceding arguments as above, but also followed by any additional
---    items in the table. This provides a more convenient interface to pass
+   items in the table. This provides a more convenient interface to pass
---    options to your completion functions.
+   options to your completion functions.
---
+
---    If this table is the last argument, it may also set the `many` key to true,
+   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.
+   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 }
---     )
 local function build(...)
     local arguments = table.pack(...)
     for i = 1, arguments.n do