Updated LuaDoc.

7 files changed, 55 insertions, 54 deletions

diff --git a/modules/textadept/adeptsense.lua b/modules/textadept/adeptsense.lua
index b76335c3..e34efbc8 100644
--- a/modules/textadept/adeptsense.lua
+++ b/modules/textadept/adeptsense.lua
@@ -395,10 +395,8 @@ M.FUNCTION = 'functions'
 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'`. Returns empty
--- strings instead of `nil`.
+-- Returns a full symbol or '' and current symbol part behind the caret or ''.
+-- For example: `buffer.cur` would return `'buffer'` and `'cur'`.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @return symbol or `''`
 -- @return part or `''`
@@ -511,8 +509,8 @@ end
 
 ---
 -- Returns the list of completions for symbol *symbol*.
--- If either *only_fields* or *only_functions* is `true`, returns the limited
--- set of completions.
+-- If either *only_fields* or *only_functions* is `true`, returns the
+-- appropriate subset of completions.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @param symbol The symbol name to get completions for.
 -- @param only_fields Optional flag indicating whether or not to return a list
@@ -570,8 +568,8 @@ end
 ---
 -- Shows an autocompletion list for the symbol behind the caret, returning
 -- `true` on success.
--- If either *only_fields* or *only_functions* is `true`, displays the limited
--- set of completions.
+-- If either *only_fields* or *only_functions* is `true`, displays the
+-- appropriate subset of completions.
 -- @param sense The Adeptsense returned by `adeptsense.new()`. If `nil`, uses
 --   the current language's Adeptsense (if it exists).
 -- @param only_fields Optional flag indicating whether or not to return a list
@@ -604,8 +602,8 @@ end
 
 ---
 -- Signals character(s) *c* to trigger autocompletion.
--- If either *only_fields* or *only_functions* is `true`, displays the limited
--- set of completions.
+-- If either *only_fields* or *only_functions* is `true`, displays the
+-- appropriate subset of completions.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @param c The character(s) that triggers the autocompletion. You can have up
 --   to two characters.
@@ -717,7 +715,8 @@ events.connect(events.CALL_TIP_CLICK, function(position)
 end)
 
 ---
--- Loads the Ctags file *tag_file* for autocompletions.
+-- 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
 -- recommended to pass `-n` to `ctags` in order to use line numbers instead of
@@ -801,7 +800,8 @@ end
 
 ---
 -- Prompts the user to select a known symbol of kind *kind* to jump to.
--- *title* is the filtered list dialog prompt's title.
+-- If *kind* is `nil`, displays all known symbols. *title* is the filtered list
+-- dialog prompt's title.
 -- @param sense The Adeptsense returned by `adeptsense.new()`. If `nil`, uses
 --   the current language's Adeptsense (if it exists).
 -- @param kind Optional Ctag character kind (e.g. `'f'` for a Lua function).
diff --git a/modules/textadept/command_entry.lua b/modules/textadept/command_entry.lua
index 0a51a76b..ddd78c02 100644
--- a/modules/textadept/command_entry.lua
+++ b/modules/textadept/command_entry.lua
@@ -162,7 +162,7 @@ end)
 --[[ The function below is a Lua C function.
 
 ---
--- Focuses the command entry.
+-- Opens the Lua command entry.
 -- @class function
 -- @name focus
 local focus
diff --git a/modules/textadept/editing.lua b/modules/textadept/editing.lua
index 1c842adc..1c957adf 100644
--- a/modules/textadept/editing.lua
+++ b/modules/textadept/editing.lua
@@ -22,7 +22,7 @@ local M = {}
 --   Typeover characters are defined in the [`typeover_chars`](#typeover_chars)
 --   table.
 -- @field AUTOINDENT (bool)
---   Match the previous line's indentation level when inserting a new line.
+--   Match the previous line's indentation level after inserting a new line.
 --   The default value is `true`.
 -- @field STRIP_TRAILING_SPACES (bool)
 --   Strip trailing whitespace before saving files.
@@ -202,9 +202,9 @@ function M.match_brace(select)
 end
 
 ---
--- Displays an autocompletion list, built from the set of string words *words*
--- and existing words in the buffer, for the word behind the caret, returning
--- `true` if completions were found.
+-- 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.
 -- @param words Optional list of words considered to be in the buffer,
 --   even if they are not. Words may contain [registered images][].
 --
@@ -305,7 +305,7 @@ function M.block_comment()
 end
 
 ---
--- Moves the caret to the beginning of line number *line* or user-specified
+-- Moves the caret to the beginning of line number *line* or the user-specified
 -- line, ensuring the line is visible.
 -- @param line Optional line number to go to. If `nil`, the user is prompted for
 --   one.
@@ -325,8 +325,8 @@ end
 
 ---
 -- Transposes characters intelligently.
--- If the caret is at the end of a line, the two characters before the caret are
--- transposed. Otherwise, the characters to the left and right are.
+-- If the caret is at the end of a line, transposes the two characters before
+-- the caret. Otherwise, the characters to the left and right are.
 -- @name transpose_chars
 function M.transpose_chars()
   if buffer.length == 0 then return end
diff --git a/modules/textadept/find.lua b/modules/textadept/find.lua
index f367d5fa..ed8950f0 100644
--- a/modules/textadept/find.lua
+++ b/modules/textadept/find.lua
@@ -52,9 +52,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 search for text 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')]]
@@ -78,15 +78,15 @@ events.FIND_WRAPPED = 'find_wrapped'
 local preferred_view
 
 ---
--- The table of Lua patterns matching files and folders to exclude when finding
--- in files.
+-- The table of Lua patterns matching files and directories to exclude when
+-- finding in files.
 -- The filter contains Lua patterns that match filenames to exclude, an optional
--- `folders` sub-table that contains patterns matching folders to exclude, and
--- an optional `extensions` sub-table that contains raw file extensions to
--- exclude. Any patterns starting with '!' exclude files and folders that do not
--- match the pattern that follows.
+-- `folders` sub-table that contains patterns matching directories to exclude,
+-- and an optional `extensions` sub-table that contains raw file extensions to
+-- exclude. Any patterns starting with '!' exclude files and directories that do
+-- not match the pattern that follows.
 -- The default value is `lfs.FILTER`, a filter for common binary file extensions
--- and version control folders.
+-- and version control directories.
 -- @see find_in_files
 -- @class table
 -- @name FILTER
@@ -207,8 +207,8 @@ function M.find_incremental(text, next, anchor)
 end
 
 ---
--- Searches directory *dir* or user-specified directory for files that match
--- search text and options and prints the results to a files found buffer.
+-- 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.
 -- 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.
@@ -327,7 +327,7 @@ 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 `nil`, the next or previous search result
+-- in the "Files Found" buffer, or if `nil`, 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.
diff --git a/modules/textadept/run.lua b/modules/textadept/run.lua
index 1aa68799..f796808f 100644
--- a/modules/textadept/run.lua
+++ b/modules/textadept/run.lua
@@ -14,8 +14,7 @@ local M = {}
 -- @field MARK_ERROR (number)
 --   The run or compile error marker number.
 -- @field cwd (string, Read-only)
---   The working directory for the most recently executed compile or run
---   command.
+--   The most recently executed compile or run 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.
@@ -24,7 +23,7 @@ local M = {}
 --   Arguments:
 --
 --   * `lexer`: The language's lexer name.
---   * `output`: The string output from the command.
+--   * `output`: The command's string output.
 -- @field _G.events.RUN_OUTPUT (string)
 --   Emitted after executing a language's run command.
 --   By default, output is printed to the message buffer. To override this
@@ -32,7 +31,7 @@ local M = {}
 --   Arguments:
 --
 --   * `lexer`: The language's lexer name.
---   * `output`: The string output from the command.
+--   * `output`: The command's string output.
 module('textadept.run')]]
 
 M.MARK_WARNING = _SCINTILLA.next_marker_number()
@@ -138,8 +137,8 @@ end
 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 file based on its extension or language, using the command from
--- the `compile_commands` table.
+-- Compiles the current file based on its extension or language, using the
+-- command from the `compile_commands` table.
 -- Emits a `COMPILE_OUTPUT` event.
 -- @see compile_commands
 -- @see _G.events
@@ -162,8 +161,8 @@ events.connect(events.COMPILE_OUTPUT, print_output)
 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 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 command
+-- from the `run_commands` table.
 -- Emits a `RUN_OUTPUT` event.
 -- @see run_commands
 -- @see _G.events
@@ -188,9 +187,9 @@ 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 the next or previous recognized
--- warning or error depending on boolean *next*.
--- Displays an annotation with the warning or error message, if available.
+-- 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.
 -- @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 0aa2bc23..1f314092 100644
--- a/modules/textadept/session.lua
+++ b/modules/textadept/session.lua
@@ -14,10 +14,10 @@ local M = {}
 --   Save the session when quitting.
 --   The session file saved is always `DEFAULT_SESSION`, even if a different
 --   session was loaded with [`load()`](#load).
---   The default value is `true`, but is disabled when passing the command line
---   switch `-n` or `--nosession` to Textadept.
+--   The default value is `true` unless the user passed the command line switch
+--   `-n` or `--nosession` to Textadept.
 -- @field MAX_RECENT_FILES (number)
---   The maximum number of recent files to save to session files.
+--   The maximum number of recent files to save in session files.
 --   Recent files are stored in [`io.recent_files`][].
 --   The default value is `10`.
 --
@@ -29,8 +29,8 @@ M.SAVE_ON_QUIT = true
 M.MAX_RECENT_FILES = 10
 
 ---
--- Loads session file *filename* or user-selected file, returning `true` if the
--- session file was opened and read.
+-- Loads session file *filename* or the user-selected file, returning `true` if
+-- the 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`,
@@ -116,7 +116,7 @@ events.connect(events.ARG_NONE, function()
 end)
 
 ---
--- Saves the session to file *filename* or user-selected file.
+-- Saves the session to file *filename* or the user-selected file.
 -- Saves split views, opened buffers, cursor information, and recent files.
 -- @param filename Optional absolute path to the session file to save. If `nil`,
 --   the user is prompted for one.
diff --git a/modules/textadept/snippets.lua b/modules/textadept/snippets.lua
index 0f68246e..4c3ccc33 100644
--- a/modules/textadept/snippets.lua
+++ b/modules/textadept/snippets.lua
@@ -123,9 +123,10 @@ local function new_snippet(text, trigger)
 end
 
 ---
--- Inserts snippet text *text* or the snippet associated with the trigger behind
--- the caret as a snippet, or goes to the active snippet's next placeholder,
--- ultimately only returning `false` if no action was taken.
+-- 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.
 -- @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.
@@ -151,7 +152,8 @@ end
 
 ---
 -- Jumps back to the previous snippet placeholder, reverting any changes from
--- the current one, but returns `false` only if no snippet is active.
+-- the current one.
+-- Returns `false` if no snippet is active.
 -- @return `false` if no snippet is active; `nil` otherwise.
 -- @name _previous
 function M._previous()