Updated LuaDoc.

7 files changed, 44 insertions, 48 deletions

diff --git a/core/.iconv.luadoc b/core/.iconv.luadoc
index e8892c20..ee403194 100644
--- a/core/.iconv.luadoc
+++ b/core/.iconv.luadoc
@@ -6,9 +6,9 @@
 module('string')
 
 ---
--- Converts string *text* from character set *from* to character set *to* using
--- iconv.
--- Valid character sets are [GNU iconv's character sets][] and include:
+-- Converts string *text* from encoding *from* to encoding *to* using iconv,
+-- returning the string result.
+-- Valid encodings are [GNU iconv's encodings][] and include:
 --
 --   * European: ASCII, ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16}, KOI8-R, KOI8-U,
 --     KOI8-RU, CP{1250,1251,1252,1253,1254,1257}, CP{850,866,1131},
@@ -31,8 +31,8 @@ module('string')
 --   * Unicode: UTF-8, UCS-2, UCS-2BE, UCS-2LE, UCS-4, UCS-4BE, UCS-4LE, UTF-16,
 --     UTF-16BE, UTF-16LE, UTF-32, UTF-32BE, UTF-32LE, UTF-7, C99, JAVA.
 --
--- [GNU iconv's character sets]: http://www.gnu.org/software/libiconv/
+-- [GNU iconv's encodings]: http://www.gnu.org/software/libiconv/
 -- @param text The text to convert.
--- @param to The string character set to convert to.
--- @param from The string character set to convert from.
+-- @param to The string encoding to convert to.
+-- @param from The string encoding to convert from.
 function iconv(text, to, from) end
diff --git a/core/.view.luadoc b/core/.view.luadoc
index 949ee997..29509f9b 100644
--- a/core/.view.luadoc
+++ b/core/.view.luadoc
@@ -5,7 +5,8 @@
 ---
 -- A Textadept view object.
 -- @field size (number)
---   The position of the split resizer (if this view is part of a split view).
+--   The pixel position of the split resizer if this view is part of a split
+--   view.
 module('view')
 
 ---
@@ -15,7 +16,7 @@ module('view')
 local buffer
 
 ---
--- Splits the view into top and bottom views, unless *vertical* is `true`,
+-- Splits the view into top and bottom views unless *vertical* is `true`,
 -- focuses the new view, and returns both the old and new views.
 -- If *vertical* is `false`, splits the view vertically into left and
 -- right views.
diff --git a/core/events.lua b/core/events.lua
index 658d011b..b7b9771d 100644
--- a/core/events.lua
+++ b/core/events.lua
@@ -29,7 +29,7 @@ local M = {}
 -- handler handled it.
 --
 -- @field APPLEEVENT_ODOC (string)
---   Emitted when Mac OSX tells Textadept to open a document.
+--   Emitted when Mac OSX tells Textadept to open a file.
 --   Arguments:
 --
 --   * _`uri`_: The UTF-8-encoded URI to open.
@@ -45,8 +45,7 @@ local M = {}
 --   Arguments:
 --
 --   * _`text`_: The text of the selection.
---   * _`position`_: The position in the buffer of the beginning of the
---     autocompleted word.
+--   * _`position`_: The position of the beginning of the autocompleted word.
 -- @field BUFFER_AFTER_SWITCH (string)
 --   Emitted right after switching to another buffer.
 --   Emitted by [`view:goto_buffer()`][].
@@ -86,9 +85,8 @@ local M = {}
 --
 --   * _`position`_: The position in the buffer double-clicked.
 --   * _`line`_: The line number double-clicked.
---   * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are
---     `buffer.SCMOD_ALT`, `buffer.SCMOD_CTRL`, `buffer.SCMOD_SHIFT`, and
---     `buffer.SCMOD_META`.
+--   * _`modifiers`_: A bit-mask of any modifier keys used: `buffer.SCMOD_CTRL`,
+--     `buffer.SCMOD_SHIFT`, `buffer.SCMOD_ALT`, and `buffer.SCMOD_META`.
 --     Note: If you set `buffer.rectangular_selection_modifier` to
 --     `buffer.SCMOD_CTRL`, the "Control" modifier is reported as *both*
 --     "Control" and "Alt" due to a Scintilla limitation with GTK+.
@@ -123,9 +121,8 @@ local M = {}
 --   Arguments:
 --
 --   * _`position`_: The position in the buffer clicked.
---   * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are
---     `buffer.SCMOD_ALT`, `buffer.SCMOD_CTRL`, `buffer.SCMOD_SHIFT`, and
---     `buffer.SCMOD_META`.
+--   * _`modifiers`_: A bit-mask of any modifier keys used: `buffer.SCMOD_CTRL`,
+--     `buffer.SCMOD_SHIFT`, `buffer.SCMOD_ALT`, and `buffer.SCMOD_META`.
 --     Note: If you set `buffer.rectangular_selection_modifier` to
 --     `buffer.SCMOD_CTRL`, the "Control" modifier is reported as *both*
 --     "Control" and "Alt" due to a Scintilla limitation with GTK+.
@@ -135,9 +132,8 @@ local M = {}
 --   Arguments:
 --
 --   * _`position`_: The position in the buffer double-clicked.
---   * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are
---     `buffer.SCMOD_ALT`, `buffer.SCMOD_CTRL`, `buffer.SCMOD_SHIFT`, and
---     `buffer.SCMOD_META`.
+--   * _`modifiers`_: A bit-mask of any modifier keys used: `buffer.SCMOD_CTRL`,
+--     `buffer.SCMOD_SHIFT`, `buffer.SCMOD_ALT`, and `buffer.SCMOD_META`.
 --     Note: If you set `buffer.rectangular_selection_modifier` to
 --     `buffer.SCMOD_CTRL`, the "Control" modifier is reported as *both*
 --     "Control" and "Alt" due to a Scintilla limitation with GTK+.
@@ -148,22 +144,21 @@ local M = {}
 --
 --   * _`position`_: The position in the buffer unclicked.
 -- @field INDICATOR_CLICK (string)
---   Emitted when clicking the mouse on text that has an indicator.
+--   Emitted when clicking the mouse on text that has an indicator present.
 --   Arguments:
 --
---   * _`position`_: The position in the buffer clicked.
---   * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are
---     `buffer.SCMOD_ALT`, `buffer.SCMOD_CTRL`, `buffer.SCMOD_SHIFT`, and
---     `buffer.SCMOD_META`.
+--   * _`position`_: The position of the clicked text in the buffer.
+--   * _`modifiers`_: A bit-mask of any modifier keys used: `buffer.SCMOD_CTRL`,
+--     `buffer.SCMOD_SHIFT`, `buffer.SCMOD_ALT`, and `buffer.SCMOD_META`.
 --     Note: If you set `buffer.rectangular_selection_modifier` to
 --     `buffer.SCMOD_CTRL`, the "Control" modifier is reported as *both*
 --     "Control" and "Alt" due to a Scintilla limitation with GTK+.
 -- @field INDICATOR_RELEASE (string)
---   Emitted after releasing the mouse after clicking on text that had an
---   indicator.
+--   Emitted when releasing the mouse after clicking on text that has an
+--   indicator present.
 --   Arguments:
 --
---   * _`position`_: The position in the buffer unclicked.
+--   * _`position`_: The position of the clicked text in the buffer.
 -- @field INITIALIZED (string)
 --   Emitted after Textadept finishes initializing.
 -- @field KEYPRESS (string)
@@ -182,10 +177,9 @@ local M = {}
 --
 --   * _`margin`_: The margin number clicked.
 --   * _`position`_: The position of the start of the line in the buffer whose
---     margin line was clicked.
---   * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are
---     `buffer.SCMOD_ALT`, `buffer.SCMOD_CTRL`, `buffer.SCMOD_SHIFT`, and
---     `buffer.SCMOD_META`.
+--     margin was clicked.
+--   * _`modifiers`_: A bit-mask of any modifier keys used: `buffer.SCMOD_CTRL`,
+--     `buffer.SCMOD_SHIFT`, `buffer.SCMOD_ALT`, and `buffer.SCMOD_META`.
 --     Note: If you set `buffer.rectangular_selection_modifier` to
 --     `buffer.SCMOD_CTRL`, the "Control" modifier is reported as *both*
 --     "Control" and "Alt" due to a Scintilla limitation with GTK+.
@@ -261,9 +255,10 @@ module('events')]]
 local handlers = {}
 
 ---
--- Adds function *f* to the set of event handlers for *event* at position
--- *index*, returning a handler ID for *f*. *event* is an arbitrary event name
--- that does not need to have been previously defined.
+-- Adds function *f* to the set of event handlers for event *event* at position
+-- *index*, returning the handler identifier for *f*.
+-- *event* may be any arbitrary string and does not need to have been previously
+-- defined.
 -- @param event The string event name.
 -- @param f The Lua function to connect to *event*.
 -- @param index Optional index to insert the handler into.
@@ -280,8 +275,8 @@ function M.connect(event, f, index)
 end
 
 ---
--- Removes handler ID *id*, returned by `events.connect()`, from the set of
--- event handlers for *event*.
+-- Removes handler identifier *id*, returned by `events.connect()`, from the set
+-- of handlers for event *event*.
 -- @param event The string event name.
 -- @param id ID of the handler returned by `events.connect()`.
 -- @see connect
@@ -293,9 +288,9 @@ end
 
 local error_emitted = false
 ---
--- Sequentially calls all handler functions for *event* with the given
+-- Sequentially calls all handler functions for event *event* with the given
 -- arguments.
--- *event* is an arbitrary event name that does not need to have been previously
+-- *event* may be any arbitrary string and does not need to have been previously
 -- defined. If any handler explicitly returns `true` or `false`, the event is
 -- not propagated any further, iteration ceases, and `emit()` returns that
 -- value. This is useful for stopping the propagation of an event like a
diff --git a/core/file_io.lua b/core/file_io.lua
index 2cf7f08b..967332f8 100644
--- a/core/file_io.lua
+++ b/core/file_io.lua
@@ -79,7 +79,7 @@ io.SNAPOPEN_MAX = 1000
 io.recent_files = {}
 
 ---
--- List of byte-order marks (BOMs) for identifying unicode file types.
+-- List of byte-order marks (BOMs) for identifying unicode file encodings.
 -- @class table
 -- @name boms
 io.boms = {
@@ -89,7 +89,7 @@ io.boms = {
 }
 
 ---
--- List of encodings to try to decode files as.
+-- List of encodings to attempt to decode files as.
 -- You should add to this list if you get a "Conversion failed" error when
 -- trying to open a file whose encoding is not recognized. Valid encodings are
 -- [GNU iconv's encodings][] and include:
diff --git a/core/keys.lua b/core/keys.lua
index 338c54e9..ac782df1 100644
--- a/core/keys.lua
+++ b/core/keys.lua
@@ -104,12 +104,12 @@ local M = {}
 --       c = {function3, arg1, arg2}
 --     }
 -- @field CLEAR (string)
---   The string representing the key sequence that clears the current key chain.
+--   The key that clears the current key chain.
 --   It cannot be part of a key chain.
 --   The default value is `'esc'` for the `Esc` (`⎋` on Mac OSX | `Esc` in
 --   curses) key.
 -- @field LANGUAGE_MODULE_PREFIX (string)
---   The starting key of the key chain reserved for language modules.
+--   The prefix key of the key chain reserved for language modules.
 --   The default value is `'cl'` on platforms other than Mac OSX, `'ml'`
 --   otherwise. Equivalent to `Ctrl+L` (`⌘L` on Mac OSX | `M-L` in curses).
 -- @field MODE (string)
diff --git a/core/lfs_ext.lua b/core/lfs_ext.lua
index d79800a4..36dfeffc 100644
--- a/core/lfs_ext.lua
+++ b/core/lfs_ext.lua
@@ -6,7 +6,7 @@
 module('lfs')]]
 
 ---
--- Filter table containing common binary file extensions and version control
+-- The filter table containing common binary file extensions and version control
 -- folders to exclude when iterating over files and directories using
 -- `dir_foreach` when its `exclude_FILTER` argument is `false`.
 -- @see dir_foreach
diff --git a/core/ui.lua b/core/ui.lua
index d347d724..4ef4ea70 100644
--- a/core/ui.lua
+++ b/core/ui.lua
@@ -52,7 +52,7 @@ local function _print(buffer_type, ...)
   buffer:set_save_point()
 end
 ---
--- Helper function for printing messages to buffers.
+-- Helper function for printing messages to the buffer of type *buffer_type*.
 -- Splits the view and opens a new buffer for printing messages to. If the
 -- message buffer is already open in a view, the message is printed to that
 -- view. Otherwise the view is split and the message buffer is opened or
@@ -383,7 +383,7 @@ events_connect(events.ERROR, ui.print)
 local menubar
 
 ---
--- A table containing the width and height values of the Textadept window.
+-- A table containing the width and height pixel values of the Textadept window.
 -- @class table
 -- @name size
 local size
@@ -391,8 +391,8 @@ local size
 The functions below are Lua C functions.
 
 ---
--- Displays a *kind* [gtdialog][] with the given string arguments to pass to
--- the dialog and returns a formatted string of the dialog's output.
+-- Displays a [gtdialog][] of kind *kind* with the given string arguments to
+-- pass to the dialog and returns a formatted string of the dialog's output.
 -- Table arguments containing strings are allowed and expanded in place. This is
 -- useful for filtered list dialogs with many items.
 -- For more information on gtdialog, see [http://foicica.com/gtdialog][].