Minor LuaDoc updates and spelling corrections.

9 files changed, 46 insertions, 55 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 336ef7e7..041312e9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2312,7 +2312,7 @@ Download:
 
 Bugfixes:
 
-* Fixed bug in parsing output from a cancelled dropdown dialog.
+* Fixed bug in parsing output from a canceled dropdown dialog.
 * Always use absolute file paths so sessions are saved and reloaded properly.
 * Temporarily disabled asynchronous spawning on OSX due to GLib crashes.
 
@@ -3362,7 +3362,7 @@ Download:
 
 Bugfixes:
 
-* Cancelling in [`buffer:close()`][] caused unwanted key propagation.
+* Canceling in [`buffer:close()`][] caused unwanted key propagation.
 * Correctly emit [`RUN_OUTPUT` events][].
 * Fixed bug with extra empty entry in the buffer browser.
 * Fixed incremental find in ncurses.
diff --git a/core/.buffer.luadoc b/core/.buffer.luadoc
index c3059f88..29c2fcca 100644
--- a/core/.buffer.luadoc
+++ b/core/.buffer.luadoc
@@ -176,7 +176,7 @@
 -- @field line_indentation (table)
 --   Table of column indentation amounts per line number.
 -- @field main_selection (number)
---   The number of the main, or most recent, selection.
+--   The number of the main or most recent selection.
 --   Only an existing selection can be made main.
 -- @field margin_text (table)
 --   Table of text displayed in text margins per line number.
@@ -439,8 +439,9 @@ module('buffer')
 ---
 -- Selects the range of text between positions *start_pos* to *end_pos* as the
 -- main selection, retaining all other selections as additional selections.
--- Since an empty selection still counts as a selection, use
--- `buffer.set_selection()` first when setting a list of selections.
+-- Since an empty selection (i.e. the current position) still counts as a
+-- selection, use `buffer.set_selection()` first when setting a list of
+-- selections.
 -- @param buffer A buffer.
 -- @param end_pos The caret position of the range of text to select in *buffer*.
 -- @param start_pos The anchor position of the range of text to select in
@@ -474,7 +475,7 @@ function append_text(buffer, text) end
 function auto_c_active(buffer) end
 
 ---
--- Cancels an autocompletion or user list.
+-- Cancels the displayed autocompletion or user list.
 -- @param buffer A buffer.
 function auto_c_cancel(buffer) end
 
@@ -652,11 +653,6 @@ function convert_eols(buffer, mode) end
 function copy(buffer) end
 
 ---
--- Copies the selected text or the current line to the clipboard.
--- @param buffer A buffer.
-function copy_allow_line(buffer) end
-
----
 -- Copies the range of text between positions *start_pos* and *end_pos* to the
 -- clipboard.
 -- @param buffer A buffer.
@@ -816,20 +812,6 @@ function get_last_child(buffer, line, level) end
 function get_line(buffer, line) end
 
 ---
--- Returns the position of the end of the selected text on line number *line*,
--- or `-1` if *line* has no selection.
--- @param buffer A buffer.
--- @param line The line number in *buffer* to use.
-function get_line_sel_end_position(buffer, line) end
-
----
--- Returns the position of the beginning of the selected text on line number
--- *line*, or `-1` if *line* has no selection.
--- @param buffer A buffer.
--- @param line The line number in *buffer* to use.
-function get_line_sel_start_position(buffer, line) end
-
----
 -- Returns the selected text.
 -- Multiple selections are included in order with no delimiters. Rectangular
 -- selections are included from top to bottom with end of line characters.
@@ -845,7 +827,7 @@ function get_text(buffer) end
 
 ---
 -- Moves the caret to the beginning of line number *line* and scrolls it into
--- view, regardless of whether *line* is hidden or not.
+-- view, regardless of whether or not *line* is hidden.
 -- @param buffer A buffer.
 -- @param line The line number in *buffer* to go to.
 function goto_line(buffer, line) end
@@ -1959,6 +1941,7 @@ function set_lexer(buffer, lexer) end
 --   * clear_cmd_key
 --   * clear_all_cmd_keys
 --   * clear_tab_stops
+--   * copy_allow_line
 --   * count_code_units
 --   * create_document
 --   * create_loader
@@ -1976,6 +1959,8 @@ function set_lexer(buffer, lexer) end
 --   * free_sub_styles
 --   * get_hotspot_active_back
 --   * get_hotspot_active_fore
+--   * get_line_sel_end_position
+--   * get_line_sel_start_position
 --   * get_next_tab_stop
 --   * get_range_pointer
 --   * get_styled_text
diff --git a/core/.view.luadoc b/core/.view.luadoc
index 8b24e3d8..f50ca046 100644
--- a/core/.view.luadoc
+++ b/core/.view.luadoc
@@ -445,6 +445,7 @@
 --   The alternative string representations of characters.
 --   Representations are displayed in the same way control characters are. Use
 --   the empty string for the '\0' character when assigning its representation.
+--   Characters are strings, not numeric codes.
 --   Call [`view.clear_representation()`]() to remove a representation.
 -- @field rgba_image_height (number)
 --   The height of the RGBA image to be defined using
@@ -926,7 +927,7 @@
 module('view')
 
 ---
--- The [buffer](#buffer) the view contains. (Read-only)
+-- The [buffer](#buffer) the view currently contains. (Read-only)
 -- @class table
 -- @name buffer
 local buffer
@@ -975,7 +976,7 @@ function brace_highlight_indicator(view, use_indicator, indicator) end
 function call_tip_active(view) end
 
 ---
--- Removes a call tip from view.
+-- Removes the displayed call tip from view.
 -- @param view A view.
 function call_tip_cancel(view) end
 
@@ -1013,8 +1014,8 @@ function clear_registered_images(view) end
 ---
 -- Removes the alternate string representation for character *char*.
 -- @param view A view.
--- @param char The character in `buffer.representations` to remove the alternate
---   string representation for.
+-- @param char The string character in `buffer.representations` to remove the
+--   alternate string representation for.
 function clear_representation(view, char) end
 
 ---
@@ -1027,7 +1028,7 @@ function contracted_fold_next(view, line) end
 
 ---
 -- Returns the actual line number of displayed line number *display_line*,
--- taking hidden lines into account.
+-- taking wrapped, annotated, and hidden lines into account.
 -- If *display_line* is less than or equal to `1`, returns `1`. If
 -- *display_line* is greater than the number of displayed lines, returns
 -- `buffer.line_count`.
@@ -1373,7 +1374,7 @@ function toggle_fold(view, line) end
 ---
 -- Toggles a fold point on line number *line* between expanded (where all of
 -- its child lines are displayed) and contracted (where all of its child lines
--- are hidden), and shows string *text* after the line.
+-- are hidden), and shows string *text* next to that line.
 -- *text* is drawn with style number `view.STYLE_FOLDDISPLAYTEXT`.
 -- @param view A view.
 -- @param line The line number in *view* to toggle the fold on and display
@@ -1387,9 +1388,9 @@ function toggle_fold_show_text(view, line, text) end
 function vertical_center_caret(view) end
 
 ---
--- Returns the displayed line number of actual line number *line*, taking hidden
--- lines into account, or `-1` if *line* is outside the range of lines in the
--- buffer.
+-- Returns the displayed line number of actual line number *line*, taking
+-- wrapped, annotated, and hidden lines into account, or `-1` if *line* is
+-- outside the range of lines in the buffer.
 -- Lines can occupy more than one display line if they wrap.
 -- @param view A view.
 -- @param line The line number in *view* to use.
diff --git a/core/events.lua b/core/events.lua
index bdef3cc9..34943e1d 100644
--- a/core/events.lua
+++ b/core/events.lua
@@ -46,7 +46,7 @@ local M = {}
 -- @field AUTO_C_SELECTION (string)
 --   Emitted after selecting an item from an autocompletion list, but before
 --   inserting that item into the buffer.
---   Automatic insertion can be cancelled by calling
+--   Automatic insertion can be canceled by calling
 --   [`buffer:auto_c_cancel()`]() before returning from the event handler.
 --   Arguments:
 --
@@ -71,6 +71,7 @@ local M = {}
 --   Emitted by [`buffer.delete()`]().
 -- @field BUFFER_NEW (string)
 --   Emitted after creating a new buffer.
+--   The new buffer is `buffer`.
 --   Emitted on startup and by [`buffer.new()`]().
 -- @field CALL_TIP_CLICK (string)
 --   Emitted when clicking on a calltip.
@@ -288,6 +289,7 @@ local M = {}
 --   * _`position`_: The position the list was displayed at.
 -- @field VIEW_NEW (string)
 --   Emitted after creating a new view.
+--   The new view is `view`.
 --   Emitted on startup and by [`view.split()`]().
 -- @field VIEW_BEFORE_SWITCH (string)
 --   Emitted right before switching to another view.
diff --git a/core/file_io.lua b/core/file_io.lua
index 99157cb0..eab122e4 100644
--- a/core/file_io.lua
+++ b/core/file_io.lua
@@ -85,7 +85,7 @@ io.encodings = {'UTF-8', 'ASCII', 'CP1252', 'UTF-16'}
 
 ---
 -- Opens *filenames*, a string filename or list of filenames, or the
--- user-selected filenames.
+-- user-selected filename(s).
 -- Emits a `FILE_OPENED` event.
 -- @param filenames Optional string filename or table of filenames to open. If
 --   `nil`, the user is prompted with a fileselect dialog.
@@ -382,12 +382,13 @@ io.quick_open_filters = {}
 -- If *paths* is `nil`, uses the current project's root directory, which is
 -- obtained from `io.get_project_root()`.
 -- String or list *filter* determines which files to show in the dialog, with
--- the default filter being `lfs.default_filter`. A filter consists of Lua
--- patterns that match file and directory paths to include or exclude. Exclusive
--- patterns begin with a '!'. If no inclusive patterns are given, any path is
--- initially considered. As a convenience, file extensions can be specified
--- literally instead of as a Lua pattern (e.g. '.lua' vs. '%.lua$'), and '/'
--- also matches the Windows directory separator ('[/\\]' is not needed).
+-- the default filter being `io.quick_open_filters[path]` (if it exists) or
+-- `lfs.default_filter`. A filter consists of Lua patterns that match file and
+-- directory paths to include or exclude. Exclusive patterns begin with a '!'.
+-- If no inclusive patterns are given, any path is initially considered. As a
+-- convenience, file extensions can be specified literally instead of as a Lua
+-- pattern (e.g. '.lua' vs. '%.lua$'), and '/' also matches the Windows
+-- directory separator ('[/\\]' is not needed).
 -- The number of files in the list is capped at `quick_open_max`.
 -- If *filter* is `nil` and *paths* is ultimately a string, the filter from the
 -- `io.quick_open_filters` table is used in place of `lfs.default_filter` if the
diff --git a/core/init.lua b/core/init.lua
index 32e4090a..0619afca 100644
--- a/core/init.lua
+++ b/core/init.lua
@@ -93,7 +93,7 @@ end)
 -- @field BSD (bool)
 --   Whether or not Textadept is running on BSD.
 -- @field CURSES (bool)
---   Whether or not Textadept is running in the terminal.
+--   Whether or not Textadept is running in a terminal.
 --   Curses feature incompatibilities are listed in the [Appendix][].
 --
 --   [Appendix]: manual.html#Curses.Compatibility
diff --git a/core/ui.lua b/core/ui.lua
index e7e608de..ce7aeb84 100644
--- a/core/ui.lua
+++ b/core/ui.lua
@@ -249,7 +249,7 @@ end
 -- If no view was found and *split* is `true`, splits the current view in order
 -- to show the requested file. If *split* is `false`, shifts to the next or
 -- *preferred_view* view in order to show the requested file. If *sloppy* is
--- `true`, requires only the last part of *filename* to match a buffer's
+-- `true`, requires only the basename of *filename* to match a buffer's
 -- `filename`. If the requested file was not found, it is opened in the desired
 -- view.
 -- @param filename The filename of the buffer to go to.
diff --git a/modules/textadept/editing.lua b/modules/textadept/editing.lua
index 96e4e351..941d96e6 100644
--- a/modules/textadept/editing.lua
+++ b/modules/textadept/editing.lua
@@ -645,12 +645,12 @@ local api_docs
 -- Symbols are determined by using `buffer.word_chars`.
 -- @param pos Optional position of the symbol to show documentation for. If
 --   omitted, the caret position is used.
--- @param case_insensitive Optional flag that indicates whether or not to search
+-- @param ignore_case Optional flag that indicates whether or not to search
 --   API files case-insensitively for symbols. The default value is `false`.
 -- @name show_documentation
 -- @see api_files
 -- @see buffer.word_chars
-function M.show_documentation(pos, case_insensitive)
+function M.show_documentation(pos, ignore_case)
   if view:call_tip_active() then events.emit(events.CALL_TIP_CLICK) return end
   local api_files = M.api_files[buffer:get_lexer(true)]
   if not api_files then return end
@@ -663,7 +663,7 @@ function M.show_documentation(pos, case_insensitive)
   ::lookup::
   if symbol ~= '' then
     local symbol_patt = '^' .. symbol:gsub('(%p)', '%%%1')
-    if case_insensitive then
+    if ignore_case then
       symbol_patt = symbol_patt:gsub('%a', function(ch)
         return string.format('[%s%s]', ch:upper(), ch:lower())
       end)
diff --git a/modules/textadept/find.lua b/modules/textadept/find.lua
index 22a6a376..7442276f 100644
--- a/modules/textadept/find.lua
+++ b/modules/textadept/find.lua
@@ -246,14 +246,16 @@ end})
 -- Use the `find_text`, `match_case`, `whole_word`, and `regex` fields to set
 -- the search text and option flags, respectively.
 -- A filter determines which files to search in, with the default filter being
--- `lfs.default_filter`. A filter consists of Lua patterns that match filenames
--- to include or exclude. Exclusive patterns begin with a '!'. If no inclusive
--- patterns are given, any filename is initially considered. As a convenience,
--- file extensions can be specified literally instead of as a Lua pattern (e.g.
--- '.lua' vs. '%.lua$'), and '/' also matches the Windows directory separator
--- ('[/\\]' is not needed).
+-- `ui.find.find_in_files_filters[dir]` (if it exists) or `lfs.default_filter`.
+-- A filter consists of Lua patterns that match filenames to include or exclude.
+-- Patterns are inclusive by default. Exclusive patterns begin with a '!'. If no
+-- inclusive patterns are given, any filename is initially considered. As a
+-- convenience, file extensions can be specified literally instead of as a Lua
+-- pattern (e.g. '.lua' vs. '%.lua$'), and '/' also matches the Windows
+-- directory separator ('[/\\]' is not needed).
 -- If *filter* is `nil`, the filter from the `ui.find.find_in_files_filters`
--- table is used. If that filter does not exist, `lfs.default_filter` is used.
+-- table for *dir* is used. If that filter does not exist, `lfs.default_filter`
+-- is used.
 -- @param dir Optional directory path to search. If `nil`, the user is prompted
 --   for one.
 -- @param filter Optional filter for files and directories to exclude. The