Updated LuaDoc.

5 files changed, 43 insertions, 41 deletions

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