More LuaDoc updates.

8 files changed, 90 insertions, 84 deletions

diff --git a/modules/textadept/adeptsense.lua b/modules/textadept/adeptsense.lua
index cc7c3c3c..a212381e 100644
--- a/modules/textadept/adeptsense.lua
+++ b/modules/textadept/adeptsense.lua
@@ -395,8 +395,7 @@ M.FUNCTION = 'functions'
 M.FIELD = 'fields'
 
 ---
--- Returns the full symbol or '' and the current symbol part behind the caret or
--- ''.
+-- Returns the full symbol and the current symbol part behind the caret.
 -- For example: `buffer.cur` would return `'buffer'` and `'cur'`.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @return symbol or `''`
@@ -413,11 +412,12 @@ end
 
 ---
 -- Returns the class type of *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` or a type assignment of
--- *symbol* according to `sense.syntax.type_assignments`.
+-- If *symbol* is `sense.syntax.self` and occurs inside a class definition that
+-- matches `sense.syntax.class_definition`, that class is returned. Otherwise,
+-- the buffer is searched backwards for either a type declaration of *symbol*
+-- according to the patterns in `sense.syntax.type_declarations`, or for a type
+-- assignment of *symbol* according to `sense.syntax.type_assignments`,
+-- whichever comes first.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @param symbol The symbol name to get the class of.
 -- @return class or `nil`
@@ -509,7 +509,7 @@ local function add_inherited(sense, class, only_fields, only_funcs, c, added)
 end
 
 ---
--- Returns the list of completions for symbol *symbol*.
+-- Returns the list of completions for string *symbol*.
 -- If either *only_fields* or *only_functions* is `true`, returns the
 -- appropriate subset of completions.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
@@ -602,7 +602,8 @@ function M.complete(sense, only_fields, only_functions)
 end
 
 ---
--- Signals character(s) *c* to trigger autocompletion.
+-- Allows the user to autocomplete the symbol behind the caret by typing
+-- character(s) *c*.
 -- If either *only_fields* or *only_functions* is `true`, displays the
 -- appropriate subset of completions.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
@@ -629,8 +630,9 @@ function M.add_trigger(sense, c, only_fields, only_functions)
 end
 
 ---
--- Returns the list of apidocs for symbol *symbol*.
--- The list also holds a `pos` key with the index of the apidoc to show.
+-- Returns the list of API documentation strings for string *symbol*.
+-- A `pos` key in that list holds the index of the documentation string that
+-- should be shown.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @param symbol The symbol name to get apidocs for.
 -- @return list of apidocs or `nil`
@@ -669,7 +671,7 @@ local apidocs = nil
 
 ---
 -- Shows a call tip with API documentation for the symbol behind the caret.
--- If documentation is already being shown, cycles through multiple definitions.
+-- If a call tip is already shown, cycles to the next one if it exists.
 -- @param sense The Adeptsense returned by `adeptsense.new()`. If `nil`, uses
 --   the current language's Adeptsense (if it exists).
 -- @return list of apidocs on success or `nil`.
@@ -718,18 +720,18 @@ end)
 ---
 -- Generates a set of symbol completion lists from Ctags file *tag_file* and
 -- adds the set to the Adeptsense.
--- *nolocations* indicates whether or not to store the location part of tags. If
--- `true`, `sense:goto_ctag()` cannot be used with this set of tags. It is
+-- *no_locations* indicates whether or not to store the location part of tags.
+-- If `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`.
+-- large number of symbols if *no_locations* is `false`.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @param tag_file The path of the Ctags file to load.
--- @param nolocations Optional flag indicating whether or not to discard the
+-- @param no_locations 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)
+function M.load_ctags(sense, tag_file, no_locations)
   local ctags_kinds = sense.ctags_kinds
   local completions = sense.completions
   local locations = sense.locations
@@ -752,7 +754,7 @@ function M.load_ctags(sense, tag_file, nolocations)
             local t = completions[class][kind]
             t[#t + 1] = tag_name..(kind == M.FIELD and '?1' or '?2')
             -- Update locations.
-            if not nolocations then
+            if not no_locations then
               if not locations[k] then locations[k] = {} end
               locations[k][class..'#'..tag_name] = {file_name, ex_cmd}
             end
@@ -784,7 +786,7 @@ function M.load_ctags(sense, tag_file, nolocations)
         local t = completions[''].fields
         t[#t + 1] = tag_name..'?1'
         -- Update locations.
-        if not nolocations then
+        if not no_locations then
           if not locations[k] then locations[k] = {} end
           locations[k][tag_name] = {file_name, ex_cmd}
         end
diff --git a/modules/textadept/command_entry.lua b/modules/textadept/command_entry.lua
index ddd78c02..224109c0 100644
--- a/modules/textadept/command_entry.lua
+++ b/modules/textadept/command_entry.lua
@@ -56,7 +56,7 @@ end
 
 ---
 -- Exits the current key mode, closes the command entry, and calls function *f*
--- (if given) with the command entry text as an argument.
+-- (if given) with the command entry's text as an argument.
 -- This is useful for binding keys to exit a command entry mode and perform an
 -- action with the entered text.
 -- @param f Optional function to call. It should accept the command entry text
@@ -91,9 +91,10 @@ local env = setmetatable({}, {
 })
 
 ---
--- Executes string *code* as Lua code subject to an "abbreviated" environment
--- where the contents of the `buffer`, `view`, and `ui` tables are also
--- considered as global functions and fields.
+-- Executes string *code* as Lua code that is subject to an "abbreviated"
+-- environment.
+-- In this environment, the contents of the `buffer`, `view`, and `ui` tables
+-- are also considered as global functions and fields.
 -- Prints the results of '=' expressions like in the Lua prompt.
 -- @param code The Lua code to execute.
 -- @name execute_lua
diff --git a/modules/textadept/editing.lua b/modules/textadept/editing.lua
index 8539f3f7..e110faba 100644
--- a/modules/textadept/editing.lua
+++ b/modules/textadept/editing.lua
@@ -17,7 +17,7 @@ local M = {}
 --   Matching braces are defined in the [`braces`](#braces) table.
 -- @field TYPEOVER_CHARS (bool)
 --   Move over closing brace and quote characters under the caret when typing
---   them instead of inserting them.
+--   them.
 --   The default value is `true`.
 --   Typeover characters are defined in the [`typeover_chars`](#typeover_chars)
 --   table.
@@ -55,7 +55,7 @@ M.comment_string = {actionscript='//',ada='--',antlr='//',adpl='!',ansi_c='/*|*/
 -- 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
+-- The ASCII values of opening characters are assigned to strings that contain
 -- complement characters. The default auto-paired characters are "()", "[]",
 -- "{}", "''", and """".
 -- @class table
@@ -202,9 +202,10 @@ function M.match_brace(select)
 end
 
 ---
--- Displays an autocompletion list, built from the set of words in string
--- *words* and existing words in the buffer, for the word behind the caret,
--- returning `true` if completions were found.
+-- Displays an autocompletion list for the word behind the caret, returning
+-- `true` if completions were found.
+-- The displayed list is built from existing words in the buffer and the set of
+-- words in string *words*.
 -- @param words Optional list of words considered to be in the buffer,
 --   even if they are not. Words may contain [registered images][].
 --
@@ -306,7 +307,7 @@ end
 
 ---
 -- Moves the caret to the beginning of line number *line* or the user-specified
--- line, ensuring the line is visible.
+-- line, ensuring *line* is visible.
 -- @param line Optional line number to go to. If `nil`, the user is prompted for
 --   one.
 -- @name goto_line
@@ -372,8 +373,9 @@ function M.enclose(left, right)
 end
 
 ---
--- Selects the text between strings *left* and *right* containing the caret or,
--- if already selected, toggles between selecting *left* and *right* too.
+-- Selects the text between strings *left* and *right* that enclose the caret.
+-- If that range is already selected, toggles between selecting *left* and
+-- *right* as well.
 -- @param left The left part of the enclosure.
 -- @param right The right part of the enclosure.
 -- @name select_enclosed
@@ -428,7 +430,8 @@ function M.select_paragraph()
 end
 
 ---
--- Selects all text with the current level of indentation.
+-- Selects the surrounding block of text whose lines' indentation levels are
+-- greater than or equal to the current line's level.
 -- If a text block is selected and the lines immediately above and below it are
 -- one indentation level lower, adds those lines to the selection.
 -- @name select_indented_block
@@ -450,7 +453,7 @@ function M.select_indented_block()
 end
 
 ---
--- Converts indentation between tabs and spaces based on `buffer.use_tabs`.
+-- Converts indentation between tabs and spaces according to `buffer.use_tabs`.
 -- 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.
@@ -517,10 +520,10 @@ end
 -- standard output (stdout).
 -- Standard input is as follows:
 --
--- 1. If text is selected and spans multiple lines, all text on the lines
--- containing the selection is passed as stdin. However, if the end of the
--- selection is at the beginning of a line, only the line ending delimiters from
--- the previous line are included. The rest of the line is excluded.
+-- 1. If text is selected and spans multiple lines, all text on the lines that
+-- have text selected is passed as stdin. However, if the end of the selection
+-- is at the beginning of a line, only the line ending delimiters from the
+-- previous line are included. The rest of the line is excluded.
 -- 2. If text is selected and spans a single line, only the selected text is
 -- used.
 -- 3. If no text is selected, the entire buffer is used.
diff --git a/modules/textadept/file_types.lua b/modules/textadept/file_types.lua
index de79a079..02dd3c63 100644
--- a/modules/textadept/file_types.lua
+++ b/modules/textadept/file_types.lua
@@ -18,8 +18,7 @@ module('textadept.file_types')]]
 events.LEXER_LOADED = 'lexer_loaded'
 
 ---
--- Map of file extensions (excluding the leading '.') to their associated
--- lexer names.
+-- Map of file extensions to their associated lexer names.
 -- 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
diff --git a/modules/textadept/find.lua b/modules/textadept/find.lua
index b6e471d6..57f87553 100644
--- a/modules/textadept/find.lua
+++ b/modules/textadept/find.lua
@@ -6,20 +6,21 @@ local M = ui.find
 ---
 -- Textadept's Find & Replace pane.
 -- @field find_entry_text (string)
---   The text in the find entry.
+--   The text in the "Find" entry.
 -- @field replace_entry_text (string)
---   The text in the replace entry.
+--   The text in the "Replace" entry.
 -- @field match_case (bool)
---   Match the search text case sensitively.
+--   Match search text case sensitively.
 --   The default value is `false`.
 -- @field whole_word (bool)
---   Match the search text surrounded by non-word characters in searches.
+--   Match search text only when it is surrounded by non-word characters in
+--   searches.
 --   The default value is `false`.
 -- @field lua (bool)
---   Interpret the search text as a Lua pattern.
+--   Interpret search text as a Lua pattern.
 --   The default value is `false`.
 -- @field in_files (bool)
---   Find the search text in a list of files.
+--   Find search text in a list of files.
 --   The default value is `false`.
 -- @field find_label_text (string, Write-only)
 --   The text of the "Find" label.
@@ -52,9 +53,9 @@ local M = ui.find
 --   The text of the "In files" label.
 --   This is primarily used for localization.
 -- @field _G.events.FIND_WRAPPED (string)
---   Emitted when a text search wraps, either from bottom to top when searching
---   for a next occurrence, or from top to bottom when searching for a previous
---   occurrence.
+--   Emitted when a text search wraps, either from bottom to top (when searching
+--   for a next occurrence), or from top to bottom (when searching for a
+--   previous occurrence).
 --   This is useful for implementing a more visual or audible notice when a
 --   search wraps in addition to the statusbar message.
 module('ui.find')]]
@@ -187,11 +188,11 @@ local function find_incremental(text, next, anchor)
 end
 
 ---
--- Begins an incremental search using the command entry if *text* is `nil`;
--- otherwise continues an incremental search by searching for the next or
--- previous instance of string *text* depending on boolean *next*.
+-- Begins an incremental search using the command entry if *text* is `nil`.
+-- Otherwise, continues an incremental search by searching for the next or
+-- previous instance of string *text*, depending on boolean *next*.
 -- *anchor* indicates whether or not to search for *text* starting from the
--- caret position instead of the position where the incremental search began at.
+-- caret position instead of the position where the incremental search began.
 -- Only the `match_case` find option is recognized. Normal command entry
 -- functionality is unavailable until the search is finished by pressing `Esc`
 -- (`⎋` on Mac OSX | `Esc` in curses).
@@ -210,7 +211,8 @@ end
 
 ---
 -- Searches directory *dir* or the user-specified directory for files that match
--- search text and options and prints the results to a "Files Found" buffer.
+-- search text and search options, and prints the results to a buffer titled
+-- "Files Found".
 -- Use the `find_text`, `match_case`, `whole_word`, and `lua` fields to set the
 -- search text and option flags, respectively. Use `FILTER` to set the search
 -- filter.
@@ -330,8 +332,8 @@ events.connect(events.REPLACE_ALL, replace_all)
 local function is_ff_buf(buf) return buf._type == _L['[Files Found Buffer]'] end
 ---
 -- Jumps to the source of the find in files search result on line number *line*
--- in the "Files Found" buffer or, if *line* is `nil`, the next or previous
--- search result depending on boolean *next*.
+-- in the buffer titled "Files Found" or, if *line* is `nil`, jumps to the next
+-- or previous search result, depending on boolean *next*.
 -- @param line The line number in the files found buffer that contains the
 --   search result to go to.
 -- @param next Optional flag indicating whether to go to the next search result
diff --git a/modules/textadept/run.lua b/modules/textadept/run.lua
index f796808f..9600a5d5 100644
--- a/modules/textadept/run.lua
+++ b/modules/textadept/run.lua
@@ -14,24 +14,24 @@ local M = {}
 -- @field MARK_ERROR (number)
 --   The run or compile error marker number.
 -- @field cwd (string, Read-only)
---   The most recently executed compile or run command's working directory.
+--   The most recently executed compile or run shell command's working directory.
 --   It is used for going to error messages with relative file paths.
 -- @field _G.events.COMPILE_OUTPUT (string)
---   Emitted after executing a language's compile command.
+--   Emitted when executing a language's compile shell 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 language's lexer name.
---   * `output`: The command's string output.
+--   * `output`: A line of string output from the command.
 -- @field _G.events.RUN_OUTPUT (string)
---   Emitted after executing a language's run command.
+--   Emitted when executing a language's run shell 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 language's lexer name.
---   * `output`: The command's string output.
+--   * `output`: A line of string output from the command.
 module('textadept.run')]]
 
 M.MARK_WARNING = _SCINTILLA.next_marker_number()
@@ -42,7 +42,7 @@ events.COMPILE_OUTPUT, events.RUN_OUTPUT = 'compile_output', 'run_output'
 
 local preferred_view
 
--- Executes a compile or run command.
+-- Executes a compile or run shell command.
 -- Emits a `COMPILE_OUTPUT` or `RUN_OUTPUT` event based on the `compiling` flag.
 -- @param commands Either `compile_commands` or `run_commands`.
 -- @param compiling Flag indicating whether or not the command is a compiler
@@ -109,7 +109,7 @@ local function get_error(message)
   return nil
 end
 
--- Prints the output from a run or compile command.
+-- Prints the output from a run or compile shell command.
 -- If the output is a recognized warning or error message, mark it.
 -- @param lexer The current lexer.
 -- @param output The output to print.
@@ -123,22 +123,21 @@ local function print_output(lexer, output)
 end
 
 ---
--- Map of file extensions (excluding the leading '.') or lexer names to their
--- associated "compile" shell command line strings or functions returning such
--- strings.
+-- Map of file extensions or lexer names to their associated "compile" shell
+-- command line strings or functions returning such strings.
 -- Command line strings may have the following macros:
 --
---   + `%(filepath)`: The current file's full path.
---   + `%d` or `%(filedir)`: The current file's directory path.
 --   + `%f` or `%(filename)`: The file's name, including its extension.
 --   + `%e` or `%(filename_noext)`: The file's name, excluding its extension.
+--   + `%d` or `%(filedir)`: The current file's directory path.
+--   + `%(filepath)`: The current file's full path.
 -- @class table
 -- @name compile_commands
 M.compile_commands = {actionscript='mxmlc "%f"',ada='gnatmake "%f"',ansi_c='gcc -o "%e" "%f"',antlr='antlr4 "%f"',g='antlr3 "%f"',applescript='osacompile "%f" -o "%e.scpt"',asm='nasm "%f" && ld "%e.o" -o "%e"',boo='booc "%f"',caml='ocamlc -o "%e" "%f"',csharp=WIN32 and 'csc "%f"' or 'mcs "%f"',cpp='g++ -o "%e" "%f"',coffeescript='coffee -c "%f"',context='context --nonstopmode "%f"',cuda=WIN32 and 'nvcc -o "%e.exe" "%f"' or 'nvcc -o "%e" "%f"',dmd='dmd "%f"',dot='dot -Tps "%f" -o "%e.ps"',eiffel='se c "%f"',erlang='erl -compile "%e"',fsharp=WIN32 and 'fsc.exe "%f"' or 'mono fsc.exe "%f"',fortran='gfortran -o "%e" "%f"',gap='gac -o "%e" "%f"',go='go build "%f"',groovy='groovyc "%f"',haskell=WIN32 and 'ghc -o "%e.exe" "%f"' or 'ghc -o "%e" "%f"',inform=function() return 'inform -c "'..buffer.filename:match('^(.+%.inform[/\\])Source')..'"' end,java='javac "%f"',ltx='pdflatex -file-line-error -halt-on-error "%f"',less='lessc "%f" "%e.css"',lilypond='lilypond "%f"',lisp='clisp -c "%f"',litcoffee='coffee -c "%f"',lua='luac -o "%e.luac" "%f"',markdown='markdown "%f" > "%e.html"',nemerle='ncc "%f" -out:"%e.exe"',nimrod='nimrod c "%f"',nsis='MakeNSIS "%f"',objective_c='gcc -o "%e" "%f"',pascal='fpc "%f"',perl='perl -c "%f"',php='php -l "%f"',prolog='gplc --no-top-level "%f"',python='python -m py_compile "%f"',ruby='ruby -c "%f"',sass='sass "%f" "%e.css"',scala='scalac "%f"',tex='pdflatex -file-line-error -halt-on-error "%f"',vala='valac "%f"',vb=WIN32 and 'vbc "%f"' or 'vbnc "%f"',}
 
 ---
 -- Compiles the current file based on its extension or language, using the
--- command from the `compile_commands` table.
+-- shell command from the `compile_commands` table.
 -- Emits a `COMPILE_OUTPUT` event.
 -- @see compile_commands
 -- @see _G.events
@@ -147,22 +146,21 @@ function M.compile() command(M.compile_commands, true) end
 events.connect(events.COMPILE_OUTPUT, print_output)
 
 ---
--- Map of file extensions (excluding the leading '.') or lexer names to their
--- associated "run" shell command line strings or functions returning such
--- strings.
+-- Map of file extensions or lexer names 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.
---   + `%d` or `%(filedir)`: The current file's directory path.
 --   + `%f` or `%(filename)`: The file's name, including its extension.
 --   + `%e` or `%(filename_noext)`: The file's name, excluding its extension.
+--   + `%d` or `%(filedir)`: The current file's directory path.
+--   + `%(filepath)`: The full path of the current file.
 -- @class table
 -- @name run_commands
 M.run_commands = {actionscript=WIN32 and 'start "" "%e.swf"' or OSX and 'open "file://%e.swf"' or 'xdg-open "%e.swf"',ada=WIN32 and '"%e"' or './"%e"',ansi_c=WIN32 and '"%e"' or './"%e"',applescript='osascript "%f"',asm='./"%e"',awk='awk -f "%f"',batch='"%f"',boo='booi "%f"',caml='ocamlrun "%e"',csharp=WIN32 and '"%e"' or 'mono "%e.exe"',cpp=WIN32 and '"%e"' or './"%e"',chuck='chuck "%f"',cmake='cmake -P "%f"',coffeescript='coffee "%f"',context=WIN32 and 'start "" "%e.pdf"' or OSX and 'open "%e.pdf"' or 'xdg-open "%e.pdf"',cuda=WIN32 and '"%e"' or './"%e"',dmd=WIN32 and '"%e"' or './"%e"',eiffel="./a.out",fsharp=WIN32 and '"%e"' or 'mono "%e.exe"',forth='gforth "%f" -e bye',fortran=WIN32 and '"%e"' or './"%e"',gnuplot='gnuplot "%f"',go='go run "%f"',groovy='groovy "%f"',haskell=WIN32 and '"%e"' or './"%e"',hypertext=WIN32 and 'start "" "%f"' or OSX and 'open "file://%f"' or 'xdg-open "%f"',idl='idl -batch "%f"',Io='io "%f"',java='java "%e"',javascript='node "%f"',ltx=WIN32 and 'start "" "%e.pdf"' or OSX and 'open "%e.pdf"' or 'xdg-open "%e.pdf"',less='lessc --no-color "%f"',lilypond=WIN32 and 'start "" "%e.pdf"' or OSX and 'open "%e.pdf"' or 'xdg-open "%e.pdf"',lisp='clisp "%f"',litcoffee='coffee "%f"',lua='lua -e "io.stdout:setvbuf(\'no\')" "%f"',makefile=WIN32 and 'nmake -f "%f"' or 'make -f "%f"',markdown='markdown "%f"',nemerle=WIN32 and '"%e"' or 'mono "%e.exe"',nimrod=WIN32 and '"%e"' or './"%e"',objective_c=WIN32 and '"%e"' or './"%e"',pascal=WIN32 and '"%e"' or './"%e"',perl='perl "%f"',php='php "%f"',pike='pike "%f"',pkgbuild='makepkg -p "%f"',prolog=WIN32 and '"%e"' or './"%e"',python='python "%f"',rstats=WIN32 and 'Rterm -f "%f"' or 'R -f "%f"',rebol='REBOL "%f"',rexx=WIN32 and 'rexx "%e"' or 'regina "%e"',ruby='ruby "%f"',sass='sass "%f"',scala='scala "%e"',bash='bash "%f"',csh='tcsh "%f"',sh='sh "%f"',zsh='zsh "%f"',smalltalk='gst "%f"',tcl='tclsh "%f"',tex=WIN32 and 'start "" "%e.pdf"' or OSX and 'open "%e.pdf"' or 'xdg-open "%e.pdf"',vala=WIN32 and '"%e"' or './"%e"',vb=WIN32 and '"%e"' or 'mono "%e.exe"',}
 
 ---
--- Runs the current file based on its extension or language, using the command
--- from the `run_commands` table.
+-- Runs the current file based on its extension or language, using the shell
+-- command from the `run_commands` table.
 -- Emits a `RUN_OUTPUT` event.
 -- @see run_commands
 -- @see _G.events
@@ -187,9 +185,10 @@ M.error_patterns = {--[[ANTLR]]'^error%(%d+%): (.-):(%d+):%d+: (.+)$','^warning%
 local function is_msg_buf(buf) return buf._type == _L['[Message Buffer]'] end
 ---
 -- Jumps to the source of the recognized compile/run warning or error on line
--- number *line* in the message buffer or, if *line* is `nil`, the next or
--- previous warning or error depending on boolean *next*.
--- Displays an annotation with the warning or error message if possible.
+-- number *line* in the message buffer.
+-- If *line* is `nil`, jumps to the next or previous warning or error, depending
+-- on boolean *next*. Displays an annotation with the warning or error message
+-- if possible.
 -- @param line The line number in the message buffer that contains the
 --   compile/run warning/error to go to.
 -- @param next Optional flag indicating whether to go to the next recognized
diff --git a/modules/textadept/session.lua b/modules/textadept/session.lua
index 1f314092..0e53137f 100644
--- a/modules/textadept/session.lua
+++ b/modules/textadept/session.lua
@@ -29,8 +29,8 @@ M.SAVE_ON_QUIT = true
 M.MAX_RECENT_FILES = 10
 
 ---
--- Loads session file *filename* or the user-selected file, returning `true` if
--- the session file was opened and read.
+-- Loads session file *filename* or the user-selected session, returning `true`
+-- if a session file was opened and read.
 -- Textadept restores split views, opened buffers, cursor information, and
 -- recent files.
 -- @param filename Optional absolute path to the session file to load. If `nil`,
diff --git a/modules/textadept/snippets.lua b/modules/textadept/snippets.lua
index 4c3ccc33..5d4b26d2 100644
--- a/modules/textadept/snippets.lua
+++ b/modules/textadept/snippets.lua
@@ -124,9 +124,9 @@ end
 
 ---
 -- Inserts snippet text *text* or the snippet assigned to the trigger word
--- behind the caret or, if a snippet is active, goes to the active snippet's
--- next placeholder.
--- Returns `false` if no action was taken.
+-- behind the caret.
+-- Otherwise, if a snippet is active, goes to the active snippet's next
+-- placeholder. Returns `false` if no action was taken.
 -- @param text Optional snippet text to insert. If `nil`, attempts to insert a
 --   new snippet based on the trigger, the word behind caret, and the current
 --   lexer.
@@ -169,7 +169,7 @@ function M._cancel_current()
 end
 
 ---
--- Prompts the user to select a snippet to insert from a list of global and
+-- Prompts the user to select a snippet to be inserted from a list of global and
 -- language-specific snippets.
 -- @name _select
 function M._select()