Rewrote LuaDoc.

15 files changed, 282 insertions, 262 deletions

diff --git a/modules/cpp/init.lua b/modules/cpp/init.lua
index e1c6dc67..45b6cf5d 100644
--- a/modules/cpp/init.lua
+++ b/modules/cpp/init.lua
@@ -12,11 +12,9 @@ local M = {}
 -- + `Ctrl+L, M` (`⌘L, M` on Mac OSX | `M-L, M` in ncurses)
 --   Open this module for editing.
 -- + `.`
---   When to the right of a known symbol, show an autocompletion list of fields
---   and functions.
+--   Show an autocompletion list of members for the symbol behind the caret.
 -- + `->`
---   When to the right of a known symbol, show an autocompletion list of fields
---   and functions.
+--   Show an autocompletion list of members for the symbol behind the caret.
 -- + `Shift+Enter` (`⇧↩` | `S-Enter`)
 --   Add ';' to the end of the current line and insert a newline.
 -- @field sense
@@ -74,7 +72,7 @@ end
 -- Commands.
 
 ---
--- Container for C/C++-specific key bindings.
+-- Table of C/C++-specific key bindings.
 -- @class table
 -- @name _G.keys.cpp
 keys.cpp = {
@@ -92,7 +90,7 @@ keys.cpp = {
 -- Snippets.
 
 ---
--- Container for C/C++-specific snippets.
+-- Table of C/C++-specific snippets.
 -- @class table
 -- @name _G.snippets.cpp
 if type(snippets) == 'table' then
diff --git a/modules/lua/init.lua b/modules/lua/init.lua
index 5ea32fd2..b9a2ed80 100644
--- a/modules/lua/init.lua
+++ b/modules/lua/init.lua
@@ -11,15 +11,13 @@ local M = {}
 --
 -- + `Ctrl+L, M` (`⌘L, M` on Mac OSX | `M-L, M` in ncurses)
 --   Open this module for editing.
--- + `Shift+Enter` (`⇧↩` | `S-Enter`)
---   Try to autocomplete an `if`, `while`, `for`, etc. control structures with
---   `end`.
 -- + `.`
---   When to the right of a known symbol, show an autocompletion list of fields
---   and functions.
+--   Show an autocompletion list of fields for the symbol behind the caret.
 -- + `:`
---   When to the right of a known symbol, show an autocompletion list of
---   functions only.
+--   Show an autocompletion list of functions for the symbol behind the caret.
+-- + `Shift+Enter` (`⇧↩` | `S-Enter`)
+--   Autocomplete an `if`, `while`, `for`, etc. control structure with the `end`
+--   keyword.
 -- @field sense
 --   The Lua [Adeptsense](_M.textadept.adeptsense.html).
 --   It loads user tags from *`_USERHOME`/modules/lua/tags* and user apidocs
@@ -96,7 +94,7 @@ end
 -- Commands.
 
 ---
--- Patterns for auto `end` completion for control structures.
+-- List of patterns for auto-`end` completion for control structures.
 -- @class table
 -- @name control_structure_patterns
 -- @see try_to_autocomplete_end
@@ -106,8 +104,8 @@ local control_structure_patterns = {
 }
 
 ---
--- Tries to autocomplete Lua's `end` keyword for control structures like `if`,
--- `while`, `for`, etc.
+-- Tries to autocomplete control structures like `if`, `while`, `for`, etc. with
+-- the `end` keyword.
 -- @see control_structure_patterns
 -- @name try_to_autocomplete_end
 function M.try_to_autocomplete_end()
diff --git a/modules/textadept/adeptsense.lua b/modules/textadept/adeptsense.lua
index 6f19163e..5f42fcdc 100644
--- a/modules/textadept/adeptsense.lua
+++ b/modules/textadept/adeptsense.lua
@@ -194,7 +194,7 @@ local M = {}
 --
 -- ### Summary
 --
--- The above method of setting syntax options, ctags kinds, and trigger
+-- The above method of setting syntax options, Ctags kinds, and trigger
 -- characters for an Adeptsense is sufficient for most static and some dynamic
 -- languages. The rest of this document is devoted to more complex techniques.
 --
@@ -367,7 +367,7 @@ local M = {}
 -- @field always_show_globals (bool)
 --   Include globals in the list of completions offered.
 --   Globals are classes, functions, and fields that do not belong to another
---   class. They are contained in `completions['']`.
+--   class. They are contained in `sense.completions['']`.
 --   The default value is `true`.
 -- @field FUNCTIONS (string)
 --   XPM image for Adeptsense functions.
@@ -393,7 +393,8 @@ M.FIELD = 'fields'
 ---
 -- Returns a full symbol (if any) and current symbol part (if any) behind the
 -- caret.
--- For example: `buffer.cur` would return `'buffer'` and `'cur'`.
+-- For example: `buffer.cur` would return `'buffer'` and `'cur'`. Returns empty
+-- strings instead of `nil`.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @return symbol or `''`
 -- @return part or `''`
@@ -408,11 +409,11 @@ function M.get_symbol(sense)
 end
 
 ---
--- Returns the class name for a given symbol.
--- If the symbol is `sense.syntax.self` and a class definition using the
--- `sense.syntax.class_definition` keyword is found, that class is returned.
--- Otherwise the buffer is searched backwards for a type declaration of the
--- symbol according to the patterns in `sense.syntax.type_declarations`.
+-- Returns the class name for *symbol* name.
+-- If *symbol* is `sense.syntax.self` and inside a class definition matching
+-- `sense.syntax.class_definition`, that class is returned. Otherwise the
+-- buffer is searched backwards for a type declaration of *symbol* according to
+-- the patterns in `sense.syntax.type_declarations`.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @param symbol The symbol to get the class of.
 -- @return class or `nil`
@@ -504,13 +505,14 @@ local function add_inherited(sense, class, only_fields, only_funcs, c, added)
 end
 
 ---
--- Returns a list of completions for the given symbol.
+-- Returns a list of function (unless *only_fields* is `true`) and field (unless
+-- *only_funcs* is `true`) completions for *symbol* name.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @param symbol The symbol to get completions for.
--- @param only_fields If `true`, returns list of only fields. The default value
---   is `false`.
--- @param only_functions If `true`, returns list of only functions. The default
---   value is `false`.
+-- @param only_fields Optional flag indicating whether or not to return a list
+--   of only fields. The default value is `false`.
+-- @param only_functions Optional flag indicating whether or not to return a
+--   list of only functions. The default value is `false`.
 -- @return completion_list or `nil`
 -- @name get_completions
 function M.get_completions(sense, symbol, only_fields, only_functions)
@@ -560,13 +562,15 @@ function M.get_completions(sense, symbol, only_fields, only_functions)
 end
 
 ---
--- Shows an autocompletion list for the symbol behind the caret.
+-- Shows an autocompletion list of functions (unless *only_fields* is `true`)
+-- and fields (unless *only_funcs* is `true`) for the symbol behind the caret,
+-- returning `true` on success.
 -- @param sense The Adeptsense returned by `adeptsense.new()`. If `nil`, uses
 --   the current language's Adeptsense (if it exists).
--- @param only_fields If `true`, returns list of only fields. The default value
---   is `false`.
--- @param only_functions If `true`, returns list of only functions. The default
---   value is `false`.
+-- @param only_fields Optional flag indicating whether or not to return a list
+--   of only fields. The default value is `false`.
+-- @param only_functions Optional flag indicating whether or not to return a
+--   list of only functions. The default value is `false`.
 -- @return `true` on success or `false`.
 -- @see get_symbol
 -- @see get_completions
@@ -592,14 +596,16 @@ function M.complete(sense, only_fields, only_functions)
 end
 
 ---
--- Sets the trigger for autocompletion.
+-- Sets the trigger character(s) *c* for autocompletion.
+-- If *only_fields* is `true`, the trigger only completes fields. If
+-- *only_functions* is `true`, the trigger only completes functions.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @param c The character(s) that triggers the autocompletion. You can have up
 --   to two characters.
--- @param only_fields If `true`, this trigger only completes fields. The default
---   value is `false`.
--- @param only_functions If `true`, this trigger only completes functions.
---   The default value is `false`.
+-- @param only_fields Optional flag indicating whether or not this trigger only
+--   completes fields. The default value is `false`.
+-- @param only_functions Optional flag indicating whether or not this trigger
+--   only completes functions. The default value is `false`.
 -- @usage sense:add_trigger('.')
 -- @usage sense:add_trigger(':', false, true) -- only functions
 -- @usage sense:add_trigger('->')
@@ -617,9 +623,8 @@ function M.add_trigger(sense, c, only_fields, only_functions)
 end
 
 ---
--- Returns a list of apidocs for the given symbol.
--- If there are multiple apidocs, the index of one to display is the value of
--- the `pos` key in the returned list.
+-- Returns a list of apidocs for *symbol* name.
+-- The list contains a `pos` key with the index of the apidoc to show.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @param symbol The symbol to get apidocs for.
 -- @return apidoc_list or `nil`
@@ -656,7 +661,7 @@ end
 
 local apidocs = nil
 ---
--- Shows a calltip with API documentation for the symbol behind the caret.
+-- Shows a call tip with API documentation for the symbol behind the caret.
 -- If documentation is already being shown, cycles through multiple definitions.
 -- @param sense The Adeptsense returned by `adeptsense.new()`. If `nil`, uses
 --   the current language's Adeptsense (if it exists).
@@ -705,14 +710,16 @@ events.connect(events.CALL_TIP_CLICK, function(position)
 end)
 
 ---
--- Loads the given ctags file for autocompletion.
--- It is recommended to pass `-n` to ctags in order to use line numbers instead
--- of text patterns to locate tags. This will greatly reduce memory usage for a
--- large number of symbols if `nolocations` is not `true`.
+-- Loads the Ctags file *tag_file* for autocompletions.
+-- If *nolocations* is `true`, `sense:goto_ctag()` cannot be used with this set
+-- of tags. It is recommended to pass `-n` to `ctags` in order to use line
+-- numbers instead of text patterns to locate tags. This will greatly reduce
+-- memory usage for a large number of symbols if `nolocations` is `false`.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
--- @param tag_file The path of the ctags file to load.
--- @param nolocations If `true`, does not store the locations of the tags for
---   use by `goto_ctag()`. The default value is `false`.
+-- @param tag_file The path of the Ctags file to load.
+-- @param nolocations Optional flag indicating whether or not to discard the
+--   locations of the tags for use by `sense:goto_ctag()`. The default value is
+--   `false`.
 -- @name load_ctags
 function M.load_ctags(sense, tag_file, nolocations)
   local ctags_kinds = sense.ctags_kinds
@@ -785,21 +792,21 @@ function M.load_ctags(sense, tag_file, nolocations)
 end
 
 ---
--- Displays a filtered list dialog of all known symbols of the given kind
--- (classes, functions, fields, etc.) and jumps to the source of the selected
--- one.
+-- Prompts the user to select a symbol to jump to from a list of all known
+-- symbols of kind *kind* (classes, functions, fields, etc.) shown in a filtered
+-- list dialog whose title text is *title*.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
--- @param k The ctag character kind (e.g. `'f'` for a Lua function).
+-- @param kind The Ctag character kind (e.g. `'f'` for a Lua function).
 -- @param title The title for the filtered list dialog.
 -- @name goto_ctag
-function M.goto_ctag(sense, k, title)
-  if not sense.locations[k] then return end -- no ctags loaded
+function M.goto_ctag(sense, kind, title)
+  if not sense.locations[kind] then return end -- no Ctags loaded
   local items = {}
-  local kind = sense.ctags_kinds[k]
-  for k, v in pairs(sense.locations[k]) do
-    items[#items + 1] = k:match('[^#]+$') -- symbol name
+  local kind = sense.ctags_kinds[kind]
+  for kind, v in pairs(sense.locations[kind]) do
+    items[#items + 1] = kind:match('[^#]+$') -- symbol name
     if kind == M.FUNCTION or kind == M.FIELD then
-      items[#items + 1] = k:match('^[^#]+') -- class name
+      items[#items + 1] = kind:match('^[^#]+') -- class name
     end
     items[#items + 1] = v[1]..':'..v[2]
   end
@@ -825,21 +832,21 @@ function M.goto_ctag(sense, k, title)
 end
 
 ---
--- Called by `load_ctags()` when a ctag kind is not recognized.
--- This method should be replaced with your own that is specific to the
--- language.
+-- Called by `load_ctags()` when a Ctag kind is not recognized.
+-- The parameters are extracted from Ctags' [tag format][]. This method should
+-- be replaced with your own that is specific to the language.
+--
+-- [tag format]: http://ctags.sourceforge.net/ctags.html#TAG%20FILE%20FORMAT
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @param tag_name The tag name.
 -- @param file_name The name of the file the tag belongs to.
--- @param ex_cmd The `ex_cmd` returned by ctags.
--- @param ext_fields The `ext_fields` returned by ctags.
+-- @param ex_cmd The `ex_cmd` returned by Ctags.
+-- @param ext_fields The `ext_fields` returned by Ctags.
 -- @name handle_ctag
 function M.handle_ctag(sense, tag_name, file_name, ex_cmd, ext_fields) end
 
 ---
--- Clears an Adeptsense.
--- This is necessary for loading a new ctags file or completions from a
--- different project.
+-- Clears the Adeptsense for loading new Ctags or project files.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @name clear
 function M.clear(sense)
@@ -851,7 +858,7 @@ function M.clear(sense)
 end
 
 ---
--- Called when clearing an Adeptsense.
+-- Called when clearing the Adeptsense.
 -- This function should be replaced with your own if you have any persistant
 -- objects that need to be deleted.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
@@ -859,7 +866,7 @@ end
 function M.handle_clear(sense) end
 
 ---
--- Creates a new Adeptsense for the given lexer language.
+-- Creates and returns a new Adeptsense for *lang* name.
 -- Only one sense can exist per language.
 -- @param lang The lexer language to create an Adeptsense for.
 -- @return adeptsense
@@ -883,7 +890,7 @@ function M.new(lang)
     always_show_globals = true,
 
 ---
--- Contains a map of ctags kinds to Adeptsense kinds.
+-- A map of Ctags kinds to Adeptsense kinds.
 -- Recognized kinds are `FUNCTION`, `FIELD`, and `CLASS`. Classes are quite
 -- simply containers for functions and fields so Lua modules would count as
 -- classes. Any other kinds will be passed to `handle_ctag()` for user-defined
@@ -901,13 +908,14 @@ function M.new(lang)
 ctags_kinds = {},
 
 ---
--- Contains a map of classes and a list of their inherited classes.
+-- A map of classes and a list of their inherited classes, normally populated by
+-- `load_ctags()`.
 -- @class table
 -- @name inherited_classes
 inherited_classes = {},
 
 ---
--- Contains lists of possible completions for known symbols.
+-- A list containing lists of possible completions for known symbols.
 -- Each symbol key has a table value that contains a list of field completions
 -- with a `fields` key and a list of functions completions with a `functions`
 -- key. This table is normally populated by `load_ctags()`, but can also be set
@@ -917,14 +925,14 @@ inherited_classes = {},
 completions = {},
 
 ---
--- Contains the locations of known symbols.
--- This table is populated by `load_ctags()`.
+-- A list of the locations of known symbols, normally populated by
+-- `load_ctags()`.
 -- @class table
 -- @name locations
 locations = {},
 
 ---
--- Contains a list of api files used by `show_apidoc()`.
+-- A list of api files used by `show_apidoc()`.
 -- Each line in the api file contains a symbol name (not the full symbol)
 -- followed by a space character and then the symbol's documentation. Since
 -- there may be many duplicate symbol names, it is recommended to put the full
@@ -937,35 +945,36 @@ locations = {},
 api_files = {},
 
 ---
--- Contains syntax-specific values for the language.
--- @field self The language's syntax-equivalent of `self`. Default is `'self'`.
+-- Map of language-specific syntax settings.
+-- @field self The language's syntax-equivalent of `self`. The default value is
+--   `'self'`.
 -- @field class_definition A Lua pattern representing the language's class
 --   definition syntax. The first capture returned must be the class name. A
 --   second, optional capture contains the class' superclass (if any). If no
 --   completions are found for the class name, completions for the superclass
 --   are shown (if any). Completions will not be shown for both a class and
---   superclass unless defined in a previously loaded ctags file. Also, multiple
---   superclasses cannot be recognized by this pattern; use a ctags file
+--   superclass unless defined in a previously loaded Ctags file. Also, multiple
+--   superclasses cannot be recognized by this pattern; use a Ctags file
 --   instead. The default value is `'class%s+([%w_]+)'`.
 -- @field word_chars A Lua pattern of characters allowed in a word.
---   The default is `'%w_'`.
+--   The default value is `'%w_'`.
 -- @field symbol_chars A Lua pattern of characters allowed in a symbol,
 --   including member operators. The pattern should be a character set.
---   The default is `'[%w_%.]'`.
+--   The default value is `'[%w_%.]'`.
 -- @field type_declarations A list of Lua patterns used for determining the
 --   class type of a symbol. The first capture returned must be the class name.
 --   Use `%_` to match the symbol.
 --   The default value is `'(%u[%w_%.]+)%s+%_'`.
 -- @field type_declarations_exclude A table of types to exclude, even if they
---   match a type_declaration pattern. Each excluded type is a table key and has
---   a `true` boolean value. For example, `{Foo = true}` excludes any type whose
---   name is `Foo`.
+--   match a `type_declarations` pattern. Each excluded type is a table key and
+--   has a `true` boolean value. For example, `{Foo = true}` excludes any type
+--   whose name is `Foo`.
 --   The default value is `{}`.
 -- @field type_assignments A map of Lua patterns to class types for variable
---   assignments. This is typically used for dynamically typed languages. For
---   example, `sense.type_assignments['^"'] = 'string'`  would recognize string
+--   assignments, typically used for dynamically typed languages. For example,
+--   `sense.syntax.type_assignments['^"'] = 'string'`  would recognize string
 --   assignments in Lua so the `foo` in `foo = "bar"` would be recognized as
---   type `string`. The class type value can contain pattern captures.
+--   type `string`. The class type value may contain `%n` pattern captures.
 -- @class table
 -- @name syntax
 -- @see get_class
diff --git a/modules/textadept/bookmarks.lua b/modules/textadept/bookmarks.lua
index 1b568357..e7b7a3b4 100644
--- a/modules/textadept/bookmarks.lua
+++ b/modules/textadept/bookmarks.lua
@@ -6,7 +6,7 @@ local M = {}
 ---
 -- Bookmarks for Textadept.
 -- @field MARK_BOOKMARK_COLOR (number)
---   The color used for a bookmarked line in "0xBBGGRR" format.
+--   The color, in "0xBBGGRR" format, used for a bookmarked line.
 module('_M.textadept.bookmarks')]]
 
 M.MARK_BOOKMARK_COLOR = not NCURSES and 0xB3661A or 0xFF0000
@@ -14,9 +14,10 @@ M.MARK_BOOKMARK_COLOR = not NCURSES and 0xB3661A or 0xFF0000
 local MARK_BOOKMARK = _SCINTILLA.next_marker_number()
 
 ---
--- Toggles a bookmark on the current line.
--- @param on If `true`, adds a bookmark to the current line. If `false`, removes
---   the bookmark on the current line. Otherwise, toggles a bookmark.
+-- Toggles the bookmark on the current line unless *on* is given.
+-- If *on* is `true` or `false`, adds or removes the bookmark, respectively.
+-- @param on Optional flag indicating whether to add or remove a bookmark on the
+--   current line. The default value is `nil`, toggling a bookmark.
 -- @name toggle
 function M.toggle(on)
   local buffer = buffer
@@ -52,21 +53,21 @@ local function goto_mark(f, increment, wrap_start)
 end
 
 ---
--- Goes to the next bookmark in the current buffer.
+-- Goes to the next bookmarked line in the current buffer.
 -- @name goto_next
 function M.goto_next()
   goto_mark(buffer.marker_next, 1, 0)
 end
 
 ---
--- Goes to the previous bookmark in the current buffer.
+-- Goes to the previous bookmarked line in the current buffer.
 -- @name goto_prev
 function M.goto_prev()
   goto_mark(buffer.marker_previous, -1, buffer.line_count)
 end
 
 ---
--- Goes to selected bookmark from a filtered list.
+-- Prompts the user to select a bookmarked line to go to.
 -- @name goto_bookmark
 function M.goto_bookmark()
   local buffer = buffer
diff --git a/modules/textadept/command_entry.lua b/modules/textadept/command_entry.lua
index 6226ff6c..149c37c8 100644
--- a/modules/textadept/command_entry.lua
+++ b/modules/textadept/command_entry.lua
@@ -96,9 +96,9 @@ end)
 local focus
 
 ---
--- Shows the given list of completions for the current word prefix.
--- On selection, the current word prefix is replaced with the completion. Word
--- prefix characters are alphanumerics and underscores.
+-- Shows the completion list *completions* for the current word prefix.
+-- Word prefix characters are alphanumerics and underscores. On selection, the
+-- word prefix is replaced with the completion.
 -- @param completions The table of completions to show. Non-string values are
 --   ignored.
 -- @class function
diff --git a/modules/textadept/editing.lua b/modules/textadept/editing.lua
index c7f7b755..c7c6b381 100644
--- a/modules/textadept/editing.lua
+++ b/modules/textadept/editing.lua
@@ -6,31 +6,30 @@ local M = {}
 ---
 -- Editing features for Textadept.
 -- @field AUTOPAIR (bool)
---   Opening '(', '[', '{', '"', or ''' characters are automatically
---   closed.
+--   Automatically close opening '(', '[', '{', '"', or '''
+--   characters.
 --   The default value is `true`.
 --   Auto-paired characters are defined in the [`char_matches`](#char_matches)
 --   table.
 -- @field HIGHLIGHT_BRACES (bool)
---   Highlight matching "()[]{}" characters.
+--   Highlight matching brace characters like "()[]{}".
 --   The default value is `true`.
 --   Matching braces are defined in the [`braces`](#braces) table.
 -- @field AUTOINDENT (bool)
---   Match the indentation level of the previous line when pressing the `Enter`
---   (`↩` on Mac OSX | `Enter` in ncurses) key.
+--   Match the indentation level of the previous line when inserting a new line.
 --   The default value is `true`.
 -- @field STRIP_WHITESPACE_ON_SAVE (bool)
 --   Strip trailing whitespace on file save.
 --   The default value is `true`.
 -- @field MARK_HIGHLIGHT_BACK (number)
---   The background color used for a line containing a
---   [highlighted word](#highlight_word) in "0xBBGGRR" format.
+--   The background color, in "0xBBGGRR" format, used for a line containing the
+--   [highlighted word](#highlight_word).
 -- @field INDIC_HIGHLIGHT_BACK (number)
---   The color used for an indicator for a [highlighted word](#highlight_word)
---   in "0xBBGGRR" format.
+--   The color, in "0xBBGGRR" format, used for an indicator for the
+--   [highlighted word](#highlight_word).
 -- @field INDIC_HIGHLIGHT_ALPHA (number)
---   The alpha transparency value between `0` (transparent) and `255` (opaque)
---   used for an indicator for a [highlighted word](#highlight_word).
+--   The alpha value, ranging from `0` (transparent) to `255` (opaque) used for
+--   an indicator for the [highlighted word](#highlight_word).
 --   The default value is `100`.
 module('_M.textadept.editing')]]
 
@@ -44,10 +43,10 @@ M.INDIC_HIGHLIGHT_BACK = 0x4D99E6
 M.INDIC_HIGHLIGHT_ALPHA = 100
 
 ---
--- Comment strings for various lexer languages.
--- Used by the `block_comment()` function. Keys are lexer language names and
--- values are the line comment delimiters for the language. This table is
--- typically populated by [language-specific modules][].
+-- Map of lexer names to line comment prefix strings for programming languages,
+-- used by the `block_comment()` function.
+-- Keys are lexer names and values are the line comment prefixes for the
+-- language. This table is typically populated by [language-specific modules][].
 --
 -- [language-specific modules]: _M.html#Block.Comment
 -- @class table
@@ -56,12 +55,12 @@ M.INDIC_HIGHLIGHT_ALPHA = 100
 M.comment_string = {}
 
 ---
--- Auto-matched characters.
--- Used for auto-matching parentheses, brackets, braces, quotes, etc. Keys are
--- lexer language names and values are tables of character match pairs. A pair's
--- key is an ASCII value and the value is the string character match. The
--- defaults are "()", "[]", "{}", "''", and """".
--- This table can be populated by language-specific modules.
+-- Map of auto-paired characters like parentheses, brackets, braces, and quotes,
+-- with language-specific auto-paired character maps assigned to a lexer name
+-- key.
+-- The ASCII values of opening characters are assigned to strings containing
+-- complement characters. The default auto-paired characters are "()", "[]",
+-- "{}", "''", and """".
 -- @class table
 -- @name char_matches
 -- @usage _M.textadept.editing.char_matches.hypertext = {..., [60] = '>'}
@@ -69,11 +68,10 @@ M.comment_string = {}
 M.char_matches = {[40] = ')', [91] = ']', [123] = '}', [39] = "'", [34] = '"'}
 
 ---
--- Highlighted brace characters.
--- Keys are lexer language names and values are tables of character ASCII values
--- that count as brace characters. The defaults are '(', ')', '[', ']', '{', and
--- '}'.
--- This table can be populated by language-specific modules.
+-- Table of brace characters to highlight, with language-specific brace
+-- character tables assigned to a lexer name key.
+-- The ASCII values of brace characters are keys and are assigned non-`nil`
+-- values. The default brace characters are '(', ')', '[', ']', '{', and '}'.
 -- @class table
 -- @name braces
 -- @usage _M.textadept.editing.braces.hypertext = {..., [60] = 1, [62] = 1}
@@ -182,8 +180,10 @@ events_connect(events.FILE_BEFORE_SAVE, function()
 end)
 
 ---
--- Goes to a matching brace position, selecting the text inside if specified to.
--- @param select If `true`, selects the text between matching braces.
+-- Goes to the current character's matching brace, selecting the text in-between
+-- if *select* is `true`.
+-- @param select Optional flag indicating whether or not to select the text
+--   between matching braces. The default value is `false`.
 -- @name match_brace
 function M.match_brace(select)
   local buffer = buffer
@@ -200,8 +200,10 @@ function M.match_brace(select)
 end
 
 ---
--- Pops up an autocompletion list for the current word based on other words in
--- the document.
+-- Displays an autocompletion list, built from the set of *default_words* and
+-- existing words in the buffer, for the word behind the caret, returning `true`
+-- if completions were found.
+-- *word_chars* contains a set of word characters.
 -- @param word_chars String of characters considered to be part of words. Since
 --   this string is used in a Lua pattern character set, character classes and
 --   ranges may be used.
@@ -260,17 +262,20 @@ function M.autocomplete_word(word_chars, default_words)
 end
 
 ---
--- Block comments or uncomments code with a given comment string.
--- If none is specified, uses the `comment_string` table.
--- @param comment The comment string inserted or removed from the beginning of
---   each line in the selection.
+-- Comments or uncomments the selected lines with line comment prefix string
+-- *prefix* or the prefix from the `comment_string` table for the current lexer.
+-- As long as any part of a line is selected, the entire line is eligible for
+-- commenting/uncommenting.
+-- @param prefix Optional prefix string inserted or removed from the beginning
+--   of each line in the selection. The default value is the prefix in the
+--   `comment_string` table for the current lexer.
 -- @see comment_string
 -- @name block_comment
-function M.block_comment(comment)
+function M.block_comment(prefix)
   local buffer = buffer
-  if not comment then
-    comment = M.comment_string[buffer:get_lexer(true)]
-    if not comment then return end
+  if not prefix then
+    prefix = M.comment_string[buffer:get_lexer(true)]
+    if not prefix then return end
   end
   local anchor, caret = buffer.selection_start, buffer.selection_end
   local s = buffer:line_from_position(anchor)
@@ -280,13 +285,13 @@ function M.block_comment(comment)
   buffer:begin_undo_action()
   for line = s, e do
     local pos = buffer:position_from_line(line)
-    if buffer:text_range(pos, pos + #comment) == comment then
-      buffer:set_sel(pos, pos + #comment)
+    if buffer:text_range(pos, pos + #prefix) == prefix then
+      buffer:set_sel(pos, pos + #prefix)
       buffer:replace_sel('')
-      caret = caret - #comment
+      caret = caret - #prefix
     else
-      buffer:insert_text(pos, comment)
-      caret = caret + #comment
+      buffer:insert_text(pos, prefix)
+      caret = caret + #prefix
     end
   end
   buffer:end_undo_action()
@@ -294,7 +299,7 @@ function M.block_comment(comment)
 end
 
 ---
--- Goes to the requested line.
+-- Goes to line number *line* or the user-specified line in the buffer.
 -- @param line Optional line number to go to. If `nil`, the user is prompted for
 --   one.
 -- @name goto_line
@@ -328,10 +333,10 @@ function M.transpose_chars()
 end
 
 ---
--- Joins the currently selected lines.
+-- Joins the currently selected lines or the current line with the line below
+-- it.
 -- As long as any part of a line is selected, the entire line is eligible for
--- joining. If no lines are selected, joins the current line with the line
--- below.
+-- joining.
 -- @name join_lines
 function M.join_lines()
   local buffer = buffer
@@ -345,9 +350,8 @@ function M.join_lines()
 end
 
 ---
--- Encloses text within a given pair of strings.
--- If text is selected, it is enclosed. Otherwise, the previous word is
--- enclosed.
+-- Encloses the selected text or the word behind the caret within strings *left*
+-- and *right*.
 -- @param left The left part of the enclosure.
 -- @param right The right part of the enclosure.
 -- @name enclose
@@ -361,7 +365,7 @@ function M.enclose(left, right)
 end
 
 ---
--- Selects text between a given pair of strings.
+-- Selects the text in-between strings *left* and *right* containing the caret.
 -- @param left The left part of the enclosure.
 -- @param right The right part of the enclosure.
 -- @name select_enclosed
@@ -373,7 +377,7 @@ function M.select_enclosed(left, right)
 end
 
 ---
--- Grows the selection by the given number of characters on either end.
+-- Grows the selected text by *amount* number of characters on either end.
 -- @param amount The number of characters to grow the selection by on either
 --   end.
 -- @name grow_selection
@@ -415,7 +419,7 @@ function M.select_paragraph()
 end
 
 ---
--- Selects indented blocks intelligently.
+-- Selects indented text blocks intelligently.
 -- If no block of text is selected, all text with the current level of
 -- indentation is selected. If a block of text is selected and the lines
 -- immediately above and below it are one indentation level lower, they are
@@ -440,9 +444,11 @@ function M.select_indented_block()
 end
 
 ---
--- Converts indentation between tabs and spaces.
--- If `buffer.use_tabs` is `true`, all indenting spaces are converted to tabs.
--- Otherwise, all indenting tabs are converted to spaces.
+-- Converts indentation between tabs and spaces depending on the buffer's
+-- indentation settings.
+-- If `buffer.use_tabs` is `true`, `buffer.tab_width` indenting spaces are
+-- converted to tabs. Otherwise, all indenting tabs are converted to
+-- `buffer.tab_width` spaces.
 -- @see buffer.use_tabs
 -- @name convert_indentation
 function M.convert_indentation()
@@ -483,8 +489,8 @@ events_connect(events.KEYPRESS, function(code)
 end)
 
 ---
--- Highlights all occurances of either the selected text or the word under the
--- caret and adds markers to the lines they are on.
+-- Highlights all occurrences of the selected text or the word under the caret
+-- and adds markers to the lines they are on.
 -- @see buffer.word_chars
 -- @name highlight_word
 function M.highlight_word()
diff --git a/modules/textadept/filter_through.lua b/modules/textadept/filter_through.lua
index e31de61f..07ef3aea 100644
--- a/modules/textadept/filter_through.lua
+++ b/modules/textadept/filter_through.lua
@@ -12,9 +12,8 @@ local tmpfile = _USERHOME..'/.ft'
 local filter_through_active = false
 
 ---
--- Prompts for a Linux, BSD, Mac OSX, or Windows shell command to filter text
--- through.
--- The standard input (stdin) for shell commands is determined as follows:
+-- Prompts the user for a Linux, BSD, Mac OSX, or Windows shell command to
+-- filter text through with standard input (stdin) as follows:
 --
 -- 1. If text is selected and spans multiple lines, all text on the lines
 -- containing the selection is used. However, if the end of the selection is at
diff --git a/modules/textadept/find.lua b/modules/textadept/find.lua
index 63faf80c..65ea70ef 100644
--- a/modules/textadept/find.lua
+++ b/modules/textadept/find.lua
@@ -11,12 +11,16 @@ local find = gui.find
 --   The text in the replace entry.
 -- @field match_case (bool)
 --   Searches are case-sensitive.
+--   The default value is `false`.
 -- @field whole_word (bool)
---   Only whole-word matches are allowed in searches.
+--   Match only whole-words in searches.
+--   The default value is `false`.
 -- @field lua (bool)
---   The search text is interpreted as a Lua pattern.
+--   Interpret search text as a Lua pattern.
+--   The default value is `false`.
 -- @field in_files (bool)
 --   Search for the text in a list of files.
+--   The default value is `false`.
 -- @field find_label_text (string, Write-only)
 --   The text of the "Find" label.
 --   This is primarily used for localization.
@@ -85,12 +89,12 @@ local escapes = {
 }
 
 ---
--- Searches the given directory for files that match search text and options and
--- prints the results to a buffer.
+-- Searches the *utf8_dir* or user-specified directory for files that match
+-- search text and options and prints the results to a buffer.
 -- Use the `find_text`, `match_case`, `whole_word`, and `lua` fields to set the
 -- search text and option flags, respectively.
--- @param utf8_dir UTF-8 encoded directory name. If `nil`, the user is prompted
--- for one.
+-- @param utf8_dir Optional UTF-8 encoded directory name to search. If `nil`,
+--   the user is prompted for one.
 -- @name find_in_files
 function find.find_in_files(utf8_dir)
   if not utf8_dir then
@@ -383,9 +387,10 @@ end
 events_connect(events.DOUBLE_CLICK, goto_file)
 
 ---
--- Goes to the next or previous file found relative to the file on the current
--- line in the results list.
--- @param next Flag indicating whether or not to go to the next file.
+-- If *next* is `true`, goes to the next file found, relative to the file on the
+-- current line in the results list. Otherwise goes to the previous file found.
+-- @param next Optional flag indicating whether or not to go to the next file.
+--   The default value is `false`.
 -- @name goto_file_in_list
 function find.goto_file_in_list(next)
   local orig_view = _VIEWS[view]
@@ -428,25 +433,25 @@ end)
 local focus
 
 ---
--- Mimicks a press of the "Find Next" button.
+-- Mimics pressing the "Find Next" button.
 -- @class function
 -- @name find_next
 local find_next
 
 ---
--- Mimicks a press of the "Find Prev" button.
+-- Mimics pressing the "Find Prev" button.
 -- @class function
 -- @name find_prev
 local find_prev
 
 ---
--- Mimicks a press of the "Replace" button.
+-- Mimics pressing the "Replace" button.
 -- @class function
 -- @name replace
 local replace
 
 ---
--- Mimicks a press of the "Replace All" button.
+-- Mimics pressing the "Replace All" button.
 -- @class function
 -- @name replace_all
 local replace_all
diff --git a/modules/textadept/keys.lua b/modules/textadept/keys.lua
index c6263f16..7f4bf8b7 100644
--- a/modules/textadept/keys.lua
+++ b/modules/textadept/keys.lua
@@ -5,8 +5,9 @@ local M = {}
 --[[ This comment is for LuaDoc.
 ---
 -- Defines key commands for Textadept.
--- This set of key commands is pretty standard among other text editors.
--- This module should be `require`d last, but before `_M.textadept.menu`.
+-- This set of key commands is pretty standard among other text editors. If
+-- applicable, load this module second to last in your *~/.textadept/init.lua*,
+-- before `_M.textadept.menu`.
 --
 -- ## Key Bindings
 --
@@ -25,7 +26,7 @@ local M = {}
 -- None          |None     |None      |Load session...
 -- Ctrl+Q        |⌘Q       |^Q        |Quit
 -- **Edit**                |         |             |
--- Ctrl+Z<br/>Alt+Backspace|⌘Z       |^Z           |Undo
+-- Ctrl+Z<br/>Alt+Bksp     |⌘Z       |^Z           |Undo
 -- Ctrl+Y<br/>Ctrl+Shift+Z |⌘⇧Z      |^Y           |Redo
 -- Ctrl+X<br/>Shift+Del    |⌘X<br/>⇧⌦|^X           |Cut
 -- Ctrl+C<br/>Ctrl+Ins     |⌘C       |^C           |Copy
@@ -113,14 +114,15 @@ local M = {}
 -- None            |None  |None         |UTF-8 encoding
 -- None            |None  |None         |ASCII encoding
 -- None            |None  |None         |ISO-8859-1 encoding
+-- None            |None  |None         |MacRoman encoding
 -- None            |None  |None         |UTF-16 encoding
 -- Ctrl+Shift+L    |⌘⇧L   |M-S-L        |Select lexer...
 -- F5              |F5    |^L<br/>F5    |Refresh syntax highlighting
 -- **View**                 |         |     |
 -- Ctrl+Alt+N               |^⌥⇥      |N/A  |Next view
 -- Ctrl+Alt+P               |^⌥⇧⇥     |N/A  |Previous view
--- Ctrl+Alt+S<br/>Ctrl+Alt+H|^S       |N/A  |Split view horizontal
--- Ctrl+Alt+V               |^V       |N/A  |Split view vertical
+-- Ctrl+Alt+S<br/>Ctrl+Alt+H|^S       |N/A  |Split view horizontally
+-- Ctrl+Alt+V               |^V       |N/A  |Split view vertically
 -- Ctrl+Alt+W               |^W       |N/A  |Unsplit view
 -- Ctrl+Alt+Shift+W         |^⇧W      |N/A  |Unsplit all views
 -- Ctrl+Alt++<br/>Ctrl+Alt+=|^+<br/>^=|N/A  |Grow view
diff --git a/modules/textadept/menu.lua b/modules/textadept/menu.lua
index f02c27a2..e224ca82 100644
--- a/modules/textadept/menu.lua
+++ b/modules/textadept/menu.lua
@@ -5,9 +5,10 @@ local M = {}
 
 --[[ This comment is for LuaDoc.
 ---
--- Provides dynamic menus for Textadept.
--- This module should be `require`d last, after `_M.textadept.keys` since it
--- looks up defined key commands to show them in menus.
+-- Defines the menus used by Textadept.
+-- If applicable, load this module last in your *~/.textadept/init.lua*, after
+-- `_M.textadept.keys` since it looks up defined key commands to show them in
+-- menus.
 module('_M.textadept.menu')]]
 
 -- Get a string uniquely identifying a key binding.
@@ -30,7 +31,8 @@ local utils = m_textadept.keys.utils
 local SEPARATOR, c = {''}, _SCINTILLA.constants
 
 ---
--- Contains the main menubar.
+-- Defines the default main menubar.
+-- Changing this field does not change the menubar. Use `set_menubar()` instead.
 -- @see set_menubar
 -- @class table
 -- @name menubar
@@ -218,7 +220,9 @@ M.menubar = {
 }
 
 ---
--- Contains the default right-click context menu.
+-- Defines the default right-click context menu.
+-- Changing this field does not change the context menu. Use `set_contextmenu()`
+-- instead.
 -- @see set_contextmenu
 -- @class table
 -- @name context_menu
@@ -287,12 +291,13 @@ local function build_command_tables(menu, title, items, commands)
 end
 
 ---
--- Sets `gui.menubar` from the given table of menus.
--- @param menubar The table of menus to create the menubar from. Each menu is
---   an ordered list of menu entries and has a `title` key for the menu/submenu
---   title. Menu entries are either submenus of the same form as menus, or
---   tables containing menu text and either a function to call or a table
---   containing the function to call with its parameters.
+-- Sets `gui.menubar` from *menubar*, a table of menus.
+-- Each menu is an ordered list of menu items and has a `title` key for the
+-- title text. Menu items are tables containing menu text and either a function
+-- to call or a table containing a function with its parameters to call when an
+-- item is clicked. Menu items may also be sub-menus, ordered lists of menu
+-- items with an additional `title` key for the sub-menu's title text.
+-- @param menubar The table of menus to create the menubar from.
 -- @see gui.menubar
 -- @see gui.menu
 -- @name set_menubar
@@ -311,24 +316,24 @@ end
 M.set_menubar(M.menubar)
 
 ---
--- Sets `gui.context_menu` from the given menu table.
--- @param menu_table The menu table to create the context menu from. The menu is
---   an ordered list of menu entries and, if applicable, has a `title` key for
---   the submenu title. Menu entries are either submenus of the same form as
---   menus, or tables containing menu text and either a function to call or a
---   table containing the function to call with its parameters.
+-- Sets `gui.context_menu` from *menu*, an ordered list of menu items.
+-- Menu items are tables containing menu text and either a function to call or
+-- a table containing a function with its parameters to call when an item is
+-- clicked. Menu items may also be sub-menus, ordered lists of menu items with
+-- an additional `title` key for the sub-menu's title text.
+-- @param menu The menu to create the context menu from.
 -- @see gui.context_menu
 -- @see gui.menu
 -- @name set_contextmenu
-function M.set_contextmenu(menu_table)
+function M.set_contextmenu(menu)
   contextmenu_actions = {}
-  gui.context_menu = gui.menu(read_menu_table(menu_table, true))
+  gui.context_menu = gui.menu(read_menu_table(menu, true))
 end
 if not NCURSES then M.set_contextmenu(M.context_menu) end
 
 local columns = {_L['Command'], _L['Key Command']}
 ---
--- Prompts the user with a filtered list dialog to run menu commands.
+-- Prompts the user to select a menu command to run.
 -- @name select_command
 function M.select_command()
   local i = gui.filteredlist(_L['Run Command'], columns, items, true,
diff --git a/modules/textadept/mime_types.lua b/modules/textadept/mime_types.lua
index 2675b9fc..2e07a3a4 100644
--- a/modules/textadept/mime_types.lua
+++ b/modules/textadept/mime_types.lua
@@ -4,14 +4,14 @@ local M = {}
 
 --[[ This comment is for LuaDoc.
 ---
--- Handles file type detection.
+-- Handles file type detection for Textadept.
 -- @field _G.events.LANGUAGE_MODULE_LOADED (string)
 --   Called after loading a language-specific module.
 --   This is useful for overriding a language-specific module's key bindings
 --   or other properties since the module is not loaded when Textadept starts.
 --   Arguments:
 --
---   * `lang`: The language lexer name.
+--   * *`lang`*: The language lexer name.
 module('_M.textadept.mime_types')]]
 
 -- Events.
@@ -19,7 +19,8 @@ local events, events_connect = events, events.connect
 events.LANGUAGE_MODULE_LOADED = 'language_module_loaded'
 
 ---
--- Table of file extensions with their associated lexers.
+-- Map of file extensions (excluding the leading '.') to their associated
+-- lexers.
 -- If the file type is not recognized by shebang words or first-line patterns,
 -- each file extension is matched against the file's extension.
 -- @class table
@@ -27,7 +28,7 @@ events.LANGUAGE_MODULE_LOADED = 'language_module_loaded'
 M.extensions = {}
 
 ---
--- Table of shebang words and their associated lexers.
+-- Map of shebang words to their associated lexers.
 -- If the file has a shebang line, a line that starts with "#!" and is the first
 -- line in the file, each shebang word is matched against that line.
 -- @class table
@@ -35,7 +36,7 @@ M.extensions = {}
 M.shebangs = {}
 
 ---
--- Table of first-line patterns and their associated lexers.
+-- Map of first-line patterns to their associated lexers.
 -- If a file type is not recognized by shebang words, each pattern is matched
 -- against the first line in the file.
 -- @class table
@@ -69,8 +70,7 @@ for line in mime_types:gmatch('[^\r\n]+') do
 end
 
 ---
--- List of detected lexers.
--- Lexers are read from *lexers/* and *~/.textadept/lexers/*.
+-- List of detected lexers are read from *lexers/* and *~/.textadept/lexers/*.
 -- @class table
 -- @name lexers
 M.lexers = {}
@@ -93,8 +93,7 @@ for lexer in pairs(lexers_found) do M.lexers[#M.lexers + 1] = lexer end
 table.sort(M.lexers)
 
 ---
--- Prompts the user to select a lexer from a filtered list for the current
--- buffer.
+-- Prompts the user to select a lexer for the current buffer.
 -- @see buffer.set_lexer
 -- @name select_lexer
 function M.select_lexer()
diff --git a/modules/textadept/run.lua b/modules/textadept/run.lua
index 149c6738..a4089e5a 100644
--- a/modules/textadept/run.lua
+++ b/modules/textadept/run.lua
@@ -11,21 +11,21 @@ local M = {}
 --
 -- [language-specific modules]: _M.html#Compile.and.Run
 -- @field _G.events.COMPILE_OUTPUT (string)
---   Called after a compile command is executed.
+--   Called after executing a language's compile command.
 --   By default, compiler output is printed to the message buffer. To override
 --   this behavior, connect to the event with an index of `1` and return `true`.
 --   Arguments:
 --
---   * `lexer`: The lexer language.
---   * `output`: The output from the command.
+--   * `lexer`: The lexer language name.
+--   * `output`: The string output from the command.
 -- @field _G.events.RUN_OUTPUT (string)
---   Called after a run command is executed.
+--   Called after executing a language's run command.
 --   By default, output is printed to the message buffer. To override this
 --   behavior, connect to the event with an index of `1` and return `true`.
 --   Arguments:
 --
---   * `lexer`: The lexer language.
---   * `output`: The output from the command.
+--   * `lexer`: The lexer language name.
+--   * `output`: The string output from the command.
 module('_M.textadept.run')]]
 
 -- Events.
@@ -110,15 +110,14 @@ local function print_output(lexer, output)
 end
 
 ---
--- File extensions and their associated "compile" shell commands.
--- Each key is a file extension whose value is a either a command line string to
--- execute or a function returning one. The command string can have the
--- following macros:
+-- Map of file extensions (excluding the leading '.') to their associated
+-- "compile" shell command line strings or functions returning such strings.
+-- Command line strings may have the following macros:
 --
 --   + `%(filepath)`: The full path of the current file.
 --   + `%(filedir)`: The current file's directory path.
---   + `%(filename)`: The name of the file including extension.
---   + `%(filename_noext)`: The name of the file excluding extension.
+--   + `%(filename)`: The name of the file, including its extension.
+--   + `%(filename_noext)`: The name of the file, excluding its extension.
 --
 -- This table is typically populated by [language-specific modules][].
 --
@@ -138,15 +137,14 @@ function M.compile() command(M.compile_command, true) end
 events_connect(events.COMPILE_OUTPUT, print_output)
 
 ---
--- File extensions and their associated "run" shell commands.
--- Each key is a file extension whose value is either a command line string to
--- execute or a function returning one. The command string can have the
--- following macros:
+-- Map of file extensions (excluding the leading '.') to their associated
+-- "run" shell command line strings or functions returning such strings.
+-- Command line strings may have the following macros:
 --
 --   + `%(filepath)`: The full path of the current file.
 --   + `%(filedir)`: The current file's directory path.
---   + `%(filename)`: The name of the file including extension.
---   + `%(filename_noext)`: The name of the file excluding extension.
+--   + `%(filename)`: The name of the file, including its extension.
+--   + `%(filename_noext)`: The name of the file, excluding its extension.
 --
 -- This table is typically populated by [language-specific modules][].
 --
@@ -166,17 +164,17 @@ function M.run() command(M.run_command) end
 events_connect(events.RUN_OUTPUT, print_output)
 
 ---
--- A table of error string details for different programming languages.
--- Each key is a lexer name whose value is a table with the following fields:
+-- Map of lexer names to their error string details, tables containing the
+-- following fields:
 --
---   + `pattern`: The Lua pattern that matches a specific error string with
---     captures for the filename the error occurs in, the line number the error
---     occurred on, and an optional error message.
---   + `filename`: The index of the Lua capture that contains the filename the
---     error occured in.
---   + `line`: The index of the Lua capture that contains the line number the
---     error occured on.
---   + `message`: (Optional) The index of the Lua capture that contains the
+--   + `pattern`: A Lua pattern that matches the language's error string,
+--     capturing the filename the error occurs in, the line number the error
+--     occurred on, and optionally the error message.
+--   + `filename`: The numeric index of the Lua capture containing the filename
+--      the error occurred in.
+--   + `line`: The numeric index of the Lua capture containing the line number
+--      the error occurred on.
+--   + `message`: (Optional) The numeric index of the Lua capture containing the
 --     error's message. An annotation will be displayed if a message was
 --     captured.
 --
@@ -190,8 +188,9 @@ events_connect(events.RUN_OUTPUT, print_output)
 M.error_detail = {}
 
 ---
--- Goes to the line in the file an error occured at based on the error message
--- at the given position and displays an annotation with the error message.
+-- Goes to line number *line_num* in the file an error occurred at based on the
+-- error message at position *pos* in the buffer and displays an annotation with
+-- the error message.
 -- This is typically called by an event handler for when the user double-clicks
 -- on an error message.
 -- @param pos The position of the caret.
diff --git a/modules/textadept/session.lua b/modules/textadept/session.lua
index 80122183..82f5415b 100644
--- a/modules/textadept/session.lua
+++ b/modules/textadept/session.lua
@@ -6,18 +6,17 @@ local M = {}
 ---
 -- Session support for Textadept.
 -- @field DEFAULT_SESSION (string)
---   The path to the default session file.
---   The default value is *`_USERHOME`/session*, or *`_USERHOME`/session_term*
---   if [`_G.NCURSES`][] is `true`.
+--   The path to the default session file, *`_USERHOME`/session*, or
+--   *`_USERHOME`/session_term* if [`_G.NCURSES`][] is `true`.
 --
 --   [`_G.NCURSES`]: _G.html#NCURSES
 -- @field SAVE_ON_QUIT (bool)
 --   Save the session when quitting.
---   The default value is `true`, but can be disabled by passing the command
---   line switch `-n` or `--nosession` to Textadept.
+--   The default value is `true`, but is disabled when passing the command line
+--   switch `-n` or `--nosession` to Textadept.
 -- @field MAX_RECENT_FILES (number)
---   The maximum number of files from [`io.recent_files`][] to save to the
---   session.
+--   The maximum number of recent files to save to the session.
+--   Recent files are stored in [`io.recent_files`][].
 --   The default value is `10`.
 --
 --   [`io.recent_files`]: io.html#recent_files
@@ -28,11 +27,12 @@ M.SAVE_ON_QUIT = true
 M.MAX_RECENT_FILES = 10
 
 ---
--- Loads a Textadept session file.
+-- Loads the Textadept session file *filename* or prompts the user to select
+-- one, returning `true` if the session file was opened and read.
 -- Textadept restores split views, opened buffers, cursor information, and
 -- recent files.
--- @param filename The absolute path to the session file to load. If `nil`, the
---   user is prompted for one.
+-- @param filename Optional absolute path to the session file to load. If `nil`,
+--   the user is prompted for one.
 -- @return `true` if the session file was opened and read; `false` otherwise.
 -- @usage _M.textadept.session.load(filename)
 -- @see DEFAULT_SESSION
@@ -122,10 +122,10 @@ events.connect('arg_none', function()
 end)
 
 ---
--- Saves a Textadept session to a file.
+-- Saves a Textadept session to file *filename* or a user-selected file.
 -- Saves split views, opened buffers, cursor information, and recent files.
--- @param filename The absolute path to the session file to save. If `nil`, the
---   user is prompted for one.
+-- @param filename Optional absolute path to the session file to save. If `nil`,
+--   the user is prompted for one.
 -- @usage _M.textadept.session.save(filename)
 -- @see DEFAULT_SESSION
 -- @name save
diff --git a/modules/textadept/snapopen.lua b/modules/textadept/snapopen.lua
index 0e91966b..48ad2783 100644
--- a/modules/textadept/snapopen.lua
+++ b/modules/textadept/snapopen.lua
@@ -6,10 +6,10 @@ local M = {}
 ---
 -- Quickly open files in a set of directories using a filtered list dialog.
 -- @field DEFAULT_DEPTH (number)
---   Maximum directory depth to search.
+--   The maximum directory depth to search.
 --   The default value is `99`.
 -- @field MAX (number)
---   Maximum number of files to list.
+--   The maximum number of files to list.
 --   The default value is `1000`.
 module('_M.textadept.snapopen')]]
 
diff --git a/modules/textadept/snippets.lua b/modules/textadept/snippets.lua
index 9654a7c2..0d85f314 100644
--- a/modules/textadept/snippets.lua
+++ b/modules/textadept/snippets.lua
@@ -130,10 +130,11 @@ local function new_snippet(text, trigger)
 end
 
 ---
--- Inserts a new snippet or goes to the next placeholder of the active snippet.
+-- Inserts snippet text *text* or the snippet associated with the trigger behind
+-- the caret as a snippet, or goes to the next placeholder of the active
+-- snippet, ultimately only returning `false` if no action was taken.
 -- @param text Optional snippet text. If `nil`, attempts to insert a new snippet
---   based on the trigger, the word to the left of the caret, and the current
---   lexer.
+--   based on the trigger, the word behind caret, and the current lexer.
 -- @return `false` if no action was taken; `nil` otherwise.
 -- @see buffer.word_chars
 -- @name _insert
@@ -157,7 +158,7 @@ end
 
 ---
 -- Goes back to the previous snippet placeholder, reverting any changes from the
--- current one.
+-- current one, but returns `false` only if no snippet is active.
 -- @return `false` if no snippet is active; `nil` otherwise.
 -- @name _previous
 function M._previous()
@@ -166,16 +167,15 @@ function M._previous()
 end
 
 ---
--- Cancels the active snippet, reverting to the state before its activation, and
--- restores the previously running snippet (if any).
+-- Cancels insertion of the active snippet.
 -- @name _cancel_current
 function M._cancel_current()
   if #snippet_stack > 0 then snippet_stack[#snippet_stack]:cancel() end
 end
 
 ---
--- Prompts the user to select a snippet to insert from a filtered list dialog.
--- Global snippets and snippets in the current lexer are shown.
+-- Prompts the user for a snippet to insert from a list of global and
+-- language-specific snippets.
 -- @name _select
 function M._select()
   local list = {}
@@ -387,9 +387,8 @@ events.connect(events.VIEW_NEW,
                function() buffer.indic_style[INDIC_SNIPPET] = INDIC_HIDDEN end)
 
 ---
--- Table of snippet triggers with their snippet text.
--- Language-specific snippets are in another table value whose key is the
--- language's lexer name.
+-- Map of snippet triggers with their snippet text, with language-specific
+-- snippets tables assigned to a lexer name key.
 -- This table also contains the `_M.textadept.snippets` module.
 -- @class table
 -- @name _G.snippets