From ff7f869ae0a02535dcc7f44a65dd3ea2fed87d01 Mon Sep 17 00:00:00 2001 From: mitchell <70453897+orbitalquark@users.noreply.github.com> Date: Sun, 11 Oct 2020 22:43:59 -0400 Subject: Updated LuaDoc. --- core/.buffer.luadoc | 7 ++++--- core/.iconv.luadoc | 1 + core/.view.luadoc | 4 ++-- core/args.lua | 60 ++++++++++++++++++++++++++--------------------------- core/events.lua | 12 +++++------ 5 files changed, 43 insertions(+), 41 deletions(-) (limited to 'core') diff --git a/core/.buffer.luadoc b/core/.buffer.luadoc index be71940a..8253f22a 100644 --- a/core/.buffer.luadoc +++ b/core/.buffer.luadoc @@ -655,8 +655,8 @@ function convert_eols(buffer, mode) end function copy(buffer) end --- --- Copies the range of text between positions *start_pos* and *end_pos* to the --- clipboard. +-- Copies to the clipboard the range of text between positions *start_pos* and +-- *end_pos*. -- @param buffer A buffer. -- @param start_pos The start position of the range of text in *buffer* to copy. -- @param end_pos The end position of the range of text in *buffer* to copy. @@ -1789,6 +1789,7 @@ function reload(buffer) end --- -- Saves the buffer to its file. +-- If the buffer does not have a file, the user is prompted for one. -- Emits `FILE_BEFORE_SAVE` and `FILE_AFTER_SAVE` events. -- @param buffer A buffer. -- @name save @@ -1815,7 +1816,7 @@ function save_as(buffer, filename) end function close(buffer, force) end --- --- Converts the current buffer's contents to encoding *encoding*. +-- Converts the buffer's contents to encoding *encoding*. -- @param buffer A buffer. -- @param encoding The string encoding to set. Valid encodings are ones that GNU -- iconv accepts. If `nil`, assumes a binary encoding. diff --git a/core/.iconv.luadoc b/core/.iconv.luadoc index 9ccbe057..adaeaea3 100644 --- a/core/.iconv.luadoc +++ b/core/.iconv.luadoc @@ -8,6 +8,7 @@ module('string') --- -- Converts string *text* from encoding *old* to encoding *new* using GNU -- libiconv, returning the string result. +-- Raises an error if the encoding conversion failed. -- Valid encodings are [GNU libiconv's encodings][] and include: -- -- * European: ASCII, ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16}, KOI8-R, KOI8-U, diff --git a/core/.view.luadoc b/core/.view.luadoc index 2cb742e2..11b0c6ca 100644 --- a/core/.view.luadoc +++ b/core/.view.luadoc @@ -88,8 +88,8 @@ -- Color the background of the line that contains the caret a different color. -- The default value is `false`. -- @field caret_line_visible_always (bool) --- Always show the caret line, even when the window is not in focus. --- The default value is `false`, showing the line only when the window is in +-- Always show the caret line, even when the view is not in focus. +-- The default value is `false`, showing the line only when the view is in -- focus. -- @field caret_period (number) -- The time between caret blinks in milliseconds. diff --git a/core/args.lua b/core/args.lua index 4a7f7eef..3d249c9a 100644 --- a/core/args.lua +++ b/core/args.lua @@ -11,34 +11,34 @@ module('args')]] events.ARG_NONE = 'arg_none' --- Contains registered command line switches. +-- Contains registered command line options. -- @class table --- @name switches -local switches = {} +-- @name options +local options = {} --- --- Registers a command line switch with short and long versions *short* and --- *long*, respectively. *narg* is the number of arguments the switch accepts, --- *f* is the function called when the switch is tripped, and *description* is --- the switch's description when displaying help. --- @param short The string short version of the switch. --- @param long The string long version of the switch. --- @param narg The number of expected parameters for the switch. --- @param f The Lua function to run when the switch is tripped. It is passed --- *narg* string arguments. --- @param description The string description of the switch for command line +-- Registers a command line option with short and long versions *short* and +-- *long*, respectively. *narg* is the number of arguments the option accepts, +-- *f* is the function called when the option is set, and *description* is +-- the option's description when displaying help. +-- @param short The string short version of the option. +-- @param long The string long version of the option. +-- @param narg The number of expected parameters for the option. +-- @param f The Lua function to run when the option is set. It is passed *narg* +-- string arguments. +-- @param description The string description of the option for command line -- help. -- @name register function M.register(short, long, narg, f, description) - local switch = { + local option = { narg = assert_type(narg, 'number', 3), f = assert_type(f, 'function', 4), description = assert_type(description, 'string', 5) } - switches[assert_type(short, 'string', 1)] = switch - switches[assert_type(long, 'string', 2)] = switch + options[assert_type(short, 'string', 1)] = option + options[assert_type(long, 'string', 2)] = option end --- Processes command line argument table *arg*, handling switches previously +-- Processes command line argument table *arg*, handling options previously -- defined using `args.register()` and treating unrecognized arguments as -- filenames to open. -- Emits an `ARG_NONE` event when no arguments are present unless @@ -50,10 +50,10 @@ local function process(arg, no_emit_arg_none) local no_args = true local i = 1 while i <= #arg do - local switch = switches[arg[i]] - if switch then - switch.f(table.unpack(arg, i + 1, i + switch.narg)) - i = i + switch.narg + local option = options[arg[i]] + if option then + option.f(table.unpack(arg, i + 1, i + option.narg)) + i = i + option.narg else local filename = lfs.abspath(arg[i], arg[-1] or lfs.currentdir()) if lfs.attributes(filename, 'mode') ~= 'directory' then @@ -72,17 +72,17 @@ events.connect(events.INITIALIZED, function() if arg then process(arg) end end) events.connect('command_line', function(arg) process(arg, true) end) if not CURSES then - -- Shows all registered command line switches on the command line. + -- Shows all registered command line options on the command line. M.register('-h', '--help', 0, function() print('Usage: textadept [args] [filenames]') local list = {} - for name in pairs(switches) do list[#list + 1] = name end + for name in pairs(options) do list[#list + 1] = name end table.sort( list, function(a, b) return a:match('[^-]+') < b:match('[^-]+') end) for _, name in ipairs(list) do - local switch = switches[name] + local option = options[name] print(string.format( - ' %s [%d args]: %s', name, switch.narg, switch.description)) + ' %s [%d args]: %s', name, option.narg, option.description)) end os.exit() end, 'Shows this') @@ -92,12 +92,12 @@ if not CURSES then quit() end, 'Prints Textadept version and copyright') -- After Textadept finishes initializing and processes arguments, remove the - -- help and version switches in order to prevent another instance from sending + -- help and version options in order to prevent another instance from sending -- '-h', '--help', '-v', and '--version' to the first instance, killing the -- latter. events.connect(events.INITIALIZED, function() - switches['-h'], switches['--help'] = nil, nil - switches['-v'], switches['--version'] = nil, nil + options['-h'], options['--help'] = nil, nil + options['-v'], options['--version'] = nil, nil end) end @@ -105,8 +105,8 @@ end -- This needs to be set as soon as possible since the processing of arguments is -- positional. _USERHOME = os.getenv(not WIN32 and 'HOME' or 'USERPROFILE') .. '/.textadept' -for i, switch in ipairs(arg) do - if (switch == '-u' or switch == '--userhome') and arg[i + 1] then +for i, option in ipairs(arg) do + if (option == '-u' or option == '--userhome') and arg[i + 1] then _USERHOME = arg[i + 1] break end diff --git a/core/events.lua b/core/events.lua index 4a1a6334..7282172d 100644 --- a/core/events.lua +++ b/core/events.lua @@ -95,8 +95,8 @@ local M = {} -- -- * _`position`_: The position double-clicked. -- * _`line`_: The line number of the position double-clicked. --- * _`modifiers`_: A bit-mask of any modifier keys used: `view.MOD_CTRL`, --- `view.MOD_SHIFT`, `view.MOD_ALT`, and `view.MOD_META`. +-- * _`modifiers`_: A bit-mask of any modifier keys held down: +-- `view.MOD_CTRL`, `view.MOD_SHIFT`, `view.MOD_ALT`, and `view.MOD_META`. -- On macOS, the Command modifier key is reported as `view.MOD_CTRL` and -- Ctrl is `view.MOD_META`. -- Note: If you set `view.rectangular_selection_modifier` to @@ -150,8 +150,8 @@ local M = {} -- Arguments: -- -- * _`position`_: The clicked text's position. --- * _`modifiers`_: A bit-mask of any modifier keys used: `view.MOD_CTRL`, --- `view.MOD_SHIFT`, `view.MOD_ALT`, and `view.MOD_META`. +-- * _`modifiers`_: A bit-mask of any modifier keys held down: +-- `view.MOD_CTRL`, `view.MOD_SHIFT`, `view.MOD_ALT`, and `view.MOD_META`. -- On macOS, the Command modifier key is reported as `view.MOD_CTRL` and -- Ctrl is `view.MOD_META`. -- Note: If you set `view.rectangular_selection_modifier` to @@ -182,8 +182,8 @@ local M = {} -- -- * _`margin`_: The margin number clicked. -- * _`position`_: The beginning position of the clicked margin's line. --- * _`modifiers`_: A bit-mask of any modifier keys used: `view.MOD_CTRL`, --- `view.MOD_SHIFT`, `view.MOD_ALT`, and `view.MOD_META`. +-- * _`modifiers`_: A bit-mask of any modifier keys held down: +-- `view.MOD_CTRL`, `view.MOD_SHIFT`, `view.MOD_ALT`, and `view.MOD_META`. -- On macOS, the Command modifier key is reported as `view.MOD_CTRL` and -- Ctrl is `view.MOD_META`. -- Note: If you set `view.rectangular_selection_modifier` to -- cgit v1.2.3