From 7f90f2f7cadce0d5b9177b16626979591bce8137 Mon Sep 17 00:00:00 2001 From: SquidDev Date: Thu, 12 Nov 2020 19:40:18 +0000 Subject: [PATCH] Clean up some examples a little bit Would be good if they didn't crash and burn on entry :). --- doc/stub/fs.lua | 2 +- doc/stub/os.lua | 6 +++++- illuaminate.sexp | 9 --------- .../data/computercraft/lua/rom/apis/colors.lua | 8 ++++---- .../data/computercraft/lua/rom/apis/disk.lua | 2 +- .../data/computercraft/lua/rom/apis/help.lua | 3 ++- .../data/computercraft/lua/rom/apis/keys.lua | 1 + .../data/computercraft/lua/rom/apis/peripheral.lua | 2 +- .../data/computercraft/lua/rom/apis/textutils.lua | 12 ++++++------ .../lua/rom/modules/main/cc/completion.lua | 4 ++-- .../computercraft/lua/rom/modules/main/cc/pretty.lua | 4 ++-- .../lua/rom/modules/main/cc/shell/completion.lua | 2 +- .../data/computercraft/lua/rom/programs/shell.lua | 4 ++-- 13 files changed, 28 insertions(+), 31 deletions(-) diff --git a/doc/stub/fs.lua b/doc/stub/fs.lua index 6e3b56c84..40b9107db 100644 --- a/doc/stub/fs.lua +++ b/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 diff --git a/doc/stub/os.lua b/doc/stub/os.lua index 7da3ea0c3..89a472bf3 100644 --- a/doc/stub/os.lua +++ b/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 diff --git a/illuaminate.sexp b/illuaminate.sexp index 80a481a64..6bf2d2688 100644 --- a/illuaminate.sexp +++ b/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)) diff --git a/src/main/resources/data/computercraft/lua/rom/apis/colors.lua b/src/main/resources/data/computercraft/lua/rom/apis/colors.lua index 83c8e0f21..ba4050763 100644 --- a/src/main/resources/data/computercraft/lua/rom/apis/colors.lua +++ b/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) diff --git a/src/main/resources/data/computercraft/lua/rom/apis/disk.lua b/src/main/resources/data/computercraft/lua/rom/apis/disk.lua index 9e136b22c..ca5ac21d2 100644 --- a/src/main/resources/data/computercraft/lua/rom/apis/disk.lua +++ 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") diff --git a/src/main/resources/data/computercraft/lua/rom/apis/help.lua b/src/main/resources/data/computercraft/lua/rom/apis/help.lua index 438af474f..777ab45bf 100644 --- a/src/main/resources/data/computercraft/lua/rom/apis/help.lua +++ b/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 = { diff --git a/src/main/resources/data/computercraft/lua/rom/apis/keys.lua b/src/main/resources/data/computercraft/lua/rom/apis/keys.lua index 90f877aa5..206646c21 100644 --- a/src/main/resources/data/computercraft/lua/rom/apis/keys.lua +++ b/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] diff --git a/src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua b/src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua index d8be09ad3..c284d0691 100644 --- a/src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua +++ b/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") diff --git a/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua b/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua index e6156d3b0..ec0633589 100644 --- a/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua +++ b/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") diff --git a/src/main/resources/data/computercraft/lua/rom/modules/main/cc/completion.lua b/src/main/resources/data/computercraft/lua/rom/modules/main/cc/completion.lua index 2ae2e4966..01cc187b1 100644 --- a/src/main/resources/data/computercraft/lua/rom/modules/main/cc/completion.lua +++ b/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) diff --git a/src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua b/src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua index a62a6f9f1..1c782ecee 100644 --- a/src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua +++ b/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 diff --git a/src/main/resources/data/computercraft/lua/rom/modules/main/cc/shell/completion.lua b/src/main/resources/data/computercraft/lua/rom/modules/main/cc/shell/completion.lua index 91d9ea7a4..21c10ec34 100644 --- a/src/main/resources/data/computercraft/lua/rom/modules/main/cc/shell/completion.lua +++ b/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 diff --git a/src/main/resources/data/computercraft/lua/rom/programs/shell.lua b/src/main/resources/data/computercraft/lua/rom/programs/shell.lua index 0c6b5868b..1cc6dfe48 100644 --- a/src/main/resources/data/computercraft/lua/rom/programs/shell.lua +++ b/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")