Continued updating documentation formatting.

6 files changed, 45 insertions, 49 deletions

diff --git a/core/.buffer.luadoc b/core/.buffer.luadoc
index 8d01f584..85396f86 100644
--- a/core/.buffer.luadoc
+++ b/core/.buffer.luadoc
@@ -104,8 +104,8 @@
 --   The default is the space character.
 -- @field auto_c_type_separator (number)
 --   The auto-completion list type-separator character byte.
---   The default is `'?'`. Autocompletion list items may display an image as
---   well as text. Each image is first registered with an integer type. Then
+--   The default is `63` ('?'). Autocompletion list items may display an image
+--   as well as text. Each image is first registered with an integer type. Then
 --   this integer is included in the text of the list separated by a '?' from
 --   the text.
 -- @field back_space_un_indents (bool)
@@ -625,8 +625,8 @@
 -- @field rgba_image_scale (number)
 --   The scale factor in percent for future RGBA image data.
 --   This is useful on OSX with a retina display where each display unit is 2
---   pixels: use a factor of 200 so that each image pixel is dsplayed using a
---   screen pixel. The default scale, 100, will stretch each image pixel to
+--   pixels: use a factor of `200` so that each image pixel is dsplayed using a
+--   screen pixel. The default scale, `100`, will stretch each image pixel to
 --   cover 4 screen pixels on a retina display.
 -- @field rgba_image_width (number)
 --   The width for future RGBA image data.
@@ -653,8 +653,8 @@
 --     The search string should be interpreted as a regular expression.
 --   * `_SCINTILLA.constants.SCFIND_POSIX` (0x00400000)
 --     Treat regular expression in a more POSIX compatible manner by
---     interpreting bare '(' and ')' for tagged sections rather than "\(" and
---     "\)".
+--     interpreting bare '(' and ')' for tagged sections rather than "\\(" and
+--     "\\)".
 -- @field sel_alpha (number)
 --   The alpha of the selection, between `0` (transparent) and `255` (opaque),
 --   or `256` for no alpha.
@@ -963,6 +963,7 @@ function auto_c_select(buffer, string) end
 
 ---
 -- Display an auto-completion list.
+-- @param buffer The global buffer.
 -- @param len_entered The number of characters before the caret used to provide
 --   the context.
 -- @param item_list List of words separated by separator characters (initially
@@ -1207,9 +1208,9 @@ function contracted_fold_next(buffer, line_start) end
 -- Converts all line endings in the document to one mode.
 -- @param buffer The global buffer.
 -- @param mode The line ending mode. Valid values are:
---   `_SCINTILLA.constants.SC_EOL_CRLF` (0),
---   `_SCINTILLA.constants.SC_EOL_CR (1)`, or
---   `_SCINTILLA.constants.SC_EOL_LF (2)`.
+--   * `_SCINTILLA.constants.SC_EOL_CRLF` (0)
+--   * `_SCINTILLA.constants.SC_EOL_CR` (1)
+--   * `_SCINTILLA.constants.SC_EOL_LF` (2)
 function convert_eo_ls(buffer, mode) end
 
 ---
@@ -1282,10 +1283,12 @@ function delete_back(buffer) end
 ---
 -- Delete the selection or if no selection, the character before the caret.
 -- Will not delete the character before at the start of a line.
+-- @param buffer The global buffer.
 function delete_back_not_line(buffer) end
 
 ---
 -- Delete a range of text in the document.
+-- @param buffer The global buffer.
 -- @param pos The start position of the range to delete.
 -- @param length The length of the range to delete.
 function delete_range(buffer, pos, length) end
@@ -1378,7 +1381,7 @@ function form_feed(buffer) end
 function get_cur_line(buffer) end
 
 ---
--- Get the back color for active hotspots in 0xBBGGRR format.
+-- Get the back color for active hotspots in "0xBBGGRR" format.
 -- @param buffer The global buffer.
 -- @return number
 function get_hotspot_active_back(buffer) end
@@ -1419,15 +1422,6 @@ function get_line_sel_end_position(buffer, line) end
 function get_line_sel_start_position(buffer, line) end
 
 ---
--- Return a read-only pointer to a range of characters in the document.
--- May move the gap so that the range is contiguous, but will only move up to
--- range_length bytes.
--- The gap is not moved unless it is within the requested range so this call can
--- be faster than `buffer.character_pointer`. This can be used by application
--- code that is able to act on blocks of text or ranges of lines.
-function get_range_pointer(buffer, position, range_length) end
-
----
 -- Retrieve the selected text.
 -- Also returns the length of the text.
 -- @param buffer The global buffer.
@@ -2030,7 +2024,7 @@ function replace_sel(buffer, text) end
 function replace_target(buffer, text) end
 
 ---
--- Replace the target text with the argument text after \d` processing.
+-- Replace the target text with the argument text after `\d` processing.
 -- Looks for `\d` where `d` is between `1` and `9` and replaces these with the
 -- strings matched in the last search operation which were surrounded by `\(`
 -- and `\)`. Returns the length of the replacement text including any change
@@ -2115,7 +2109,7 @@ function selection_duplicate(buffer) end
 -- Reset the set of characters for whitespace and word characters to the
 -- defaults.
 -- This sets whitespace to space, tab and other characters with codes less than
--- 0x20, with word characters set to alphanumeric and `'_'`.
+-- 0x20, with word characters set to alphanumeric and '_'.
 -- @param buffer The global buffer.
 function set_chars_default(buffer) end
 
@@ -2651,6 +2645,7 @@ function get_style_name(buffer, style_num) end
 --   * mod_event_mask
 --   * paste_convert_endings
 --   * character_pointer
+--   * get_range_pointer
 --   * identifier
 --   * key_words
 --   * technology
diff --git a/core/.iconv.luadoc b/core/.iconv.luadoc
index fcf199ca..78616a30 100644
--- a/core/.iconv.luadoc
+++ b/core/.iconv.luadoc
@@ -2,7 +2,7 @@
 -- This is a DUMMY FILE used for making LuaDoc for built-in functions in the
 -- string table.
 
---- Extends Lua's `string` package to provide character set conversions.
+--- Extends Lua's `string` library to provide character set conversions.
 module('string')
 
 ---
diff --git a/core/events.lua b/core/events.lua
index 3623d1b5..f68b9fed 100644
--- a/core/events.lua
+++ b/core/events.lua
@@ -78,10 +78,10 @@ local M = {}
 --   Arguments:
 --
 --   * `code`: The key code.
---   * `shift`: The Shift key is held down.
---   * `ctrl`: The Control/Command key is held down.
---   * `alt`: The Alt/option key is held down.
---   * `meta`: The Control key on Mac OSX is held down.
+--   * `shift`: The "Shift" modifier key is held down.
+--   * `ctrl`: The "Control"/"Command" modifier key is held down.
+--   * `alt`: The "Alt"/"Option" modifier key is held down.
+--   * `meta`: The "Control" modifier key on Mac OSX is held down.
 -- @field DOUBLE_CLICK (string)
 --   Called when the mouse button is double-clicked.
 --   Arguments:
@@ -94,8 +94,8 @@ local M = {}
 --     `_SCINTILLA.constants.SCMOD_SHIFT`, and
 --     `_SCINTILLA.constants.SCMOD_META`.
 --     Note: If you set `buffer.rectangular_selection_modifier` to
---     `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both*
---     Ctrl and Alt due to a Scintilla limitation with GTK+.
+--     `_SCINTILLA.constants.SCMOD_CTRL`, the "Control" modifier is reported as
+--     *both* "Control" and "Alt" due to a Scintilla limitation with GTK+.
 -- @field DWELL_END (string)
 --   Called after a `DWELL_START` and the mouse is moved or other activity such
 --   as key press indicates the dwell is over.
@@ -137,8 +137,8 @@ local M = {}
 --     `_SCINTILLA.constants.SCMOD_SHIFT`, and
 --     `_SCINTILLA.constants.SCMOD_META`.
 --     Note: If you set `buffer.rectangular_selection_modifier` to
---     `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both*
---     Ctrl and Alt due to a Scintilla limitation with GTK+.
+--     `_SCINTILLA.constants.SCMOD_CTRL`, the "Control" modifier is reported as
+--     *both* "Control" and "Alt" due to a Scintilla limitation with GTK+.
 -- @field HOTSPOT_DOUBLE_CLICK (string)
 --   Called when the user double clicks on text that is in a style with the
 --   hotspot attribute set.
@@ -151,8 +151,8 @@ local M = {}
 --     `_SCINTILLA.constants.SCMOD_SHIFT`, and
 --     `_SCINTILLA.constants.SCMOD_META`.
 --     Note: If you set `buffer.rectangular_selection_modifier` to
---     `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both*
---     Ctrl and Alt due to a Scintilla limitation with GTK+.
+--     `_SCINTILLA.constants.SCMOD_CTRL`, the "Control" modifier is reported as
+--     *both* "Control" and "Alt" due to a Scintilla limitation with GTK+.
 -- @field HOTSPOT_RELEASE_CLICK (string)
 --   Called when the user releases the mouse on text that is in a style with the
 --   hotspot attribute set.
@@ -170,8 +170,8 @@ local M = {}
 --     `_SCINTILLA.constants.SCMOD_SHIFT`, and
 --     `_SCINTILLA.constants.SCMOD_META`.
 --     Note: If you set `buffer.rectangular_selection_modifier` to
---     `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both*
---     Ctrl and Alt due to a Scintilla limitation with GTK+.
+--     `_SCINTILLA.constants.SCMOD_CTRL`, the "Control" modifier is reported as
+--     *both* "Control" and "Alt" due to a Scintilla limitation with GTK+.
 -- @field INDICATOR_RELEASE (string)
 --   Called when the user releases the mouse on text that has an indicator.
 --   Arguments:
@@ -183,10 +183,10 @@ local M = {}
 --   Arguments:
 --
 --   * `code`: The key code.
---   * `shift`: The Shift key is held down.
---   * `ctrl`: The Control/Command key is held down.
---   * `alt`: The Alt/option key is held down.
---   * `meta`: The Control key on Mac OSX is held down.
+--   * `shift`: The "Shift" modifier key is held down.
+--   * `ctrl`: The "Control"/"Command" modifier key is held down.
+--   * `alt`: The "Alt"/"Option" modifier key is held down.
+--   * `meta`: The "Control" modifier key on Mac OSX is held down.
 -- @field MARGIN_CLICK (string)
 --   Called when the mouse is clicked inside a margin.
 --   Arguments:
@@ -199,8 +199,8 @@ local M = {}
 --     and `_SCINTILLA.constants.SCI_ALT` to indicate the keys that were held
 --     down at the time of the margin click.
 --     Note: If you set `buffer.rectangular_selection_modifier` to
---     `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both*
---     Ctrl and Alt due to a Scintilla limitation with GTK+.
+--     `_SCINTILLA.constants.SCMOD_CTRL`, the "Control" modifier is reported as
+--     *both* "Control" and "Alt" due to a Scintilla limitation with GTK+.
 -- @field MENU_CLICKED (string)
 --   Called when a menu item is selected.
 --   Arguments:
@@ -283,7 +283,7 @@ M.handlers = {}
 -- @param f The Lua function to add.
 -- @param index Optional index to insert the handler into.
 -- @return Index of handler.
--- @usage events.connect('my_event', function(message) gui.print(message) end)
+-- @usage events.connect('my_event', function(msg) gui.print(msg) end)
 -- @see disconnect
 -- @name connect
 function M.connect(event, f, index)
diff --git a/core/file_io.lua b/core/file_io.lua
index cbd93b22..2582933c 100644
--- a/core/file_io.lua
+++ b/core/file_io.lua
@@ -2,7 +2,7 @@
 
 --[[ This comment is for LuaDoc.
 ---
--- Extends Lua's `io` package with Textadept functions for working with files.
+-- Extends Lua's `io` library with Textadept functions for working with files.
 --
 -- ## Working with UTF-8
 --
diff --git a/core/gui.lua b/core/gui.lua
index 4bc3da8c..3e0db83e 100644
--- a/core/gui.lua
+++ b/core/gui.lua
@@ -65,8 +65,8 @@ function gui._print(buffer_type, ...) pcall(_print, buffer_type, ...) end
 function gui.print(...) gui._print(_L['[Message Buffer]'], ...) end
 
 ---
--- Shortcut function for `gui.dialog('filteredlist', ...)` with 'Ok' and
--- 'Cancel' buttons.
+-- Shortcut function for `gui.dialog('filteredlist', ...)` with "Ok" and
+-- "Cancel" buttons.
 -- @param title The title for the filtered list dialog.
 -- @param columns A column name or list of column names.
 -- @param items An item or list of items.
@@ -157,8 +157,9 @@ local THEME
 -- themes of the same name in *`_HOME`/themes/*. If the name contains slashes
 -- ('\' on Windows, '/' otherwise), it is assumed to be an absolute path to a
 -- theme instead of a theme name. An error is thrown if the theme is not found.
--- Any errors in the theme are printed to `io.stderr`.
--- @param name The name or absolute path of a theme. If nil, sets the default
+-- Any errors in the theme are printed to `io.stderr`. Running Textadept from a
+-- terminal is the easiest way to see errors as they occur.
+-- @param name The name or absolute path of a theme. If `nil`, sets the default
 --   theme.
 -- @name set_theme
 function gui.set_theme(name)
diff --git a/core/keys.lua b/core/keys.lua
index e3ed5d73..6cd81953 100644
--- a/core/keys.lua
+++ b/core/keys.lua
@@ -54,7 +54,7 @@ local M = {}
 --
 -- Commands associated with key sequences can be either Lua functions, or
 -- tables containing Lua functions with a set of arguments to call the function
--- with. Examples are
+-- with. Examples are:
 --
 --     keys['cn'] = new_buffer
 --     keys['cs'] = buffer.save
@@ -70,7 +70,7 @@ local M = {}
 -- assigned to one key sequence. Language-specific modules
 -- [use key chains](#LANGUAGE_MODULE_PREFIX) for their functions. By default,
 -- the `Esc` (`⎋` on Mac OSX | `Esc` in ncurses) key cancels a key chain, but it
--- can be redefined via [`CLEAR`](#CLEAR). An example key chain looks like
+-- can be redefined via [`CLEAR`](#CLEAR). An example key chain looks like:
 --
 --     keys['aa'] = {
 --       a = function1,
@@ -105,7 +105,7 @@ local getmetatable = getmetatable
 local error = function(e) events.emit(events.ERROR, e) end
 
 ---
--- Lookup table for string representations of GDK key codes higher than 255.
+-- Lookup table for string representations of key codes higher than 255.
 -- Key codes can be identified by temporarily uncommenting the `print()`
 -- statements in *core/keys.lua*
 -- @class table