Rewrote some LuaDoc to use the active voice.

7 files changed, 142 insertions, 150 deletions

diff --git a/core/._M.luadoc b/core/._M.luadoc
index 7b459468..9eb70f64 100644
--- a/core/._M.luadoc
+++ b/core/._M.luadoc
@@ -9,21 +9,21 @@
 -- ## Module Guidelines
 --
 -- At the very least, modules consist of a single directory with an *init.lua*
--- script. However, the script can load additional Lua files present in the
+-- script. However, the script may load additional Lua files present in the
 -- directory. (For an example, see *modules/textadept/init.lua*.)
 --
--- Once modules are loaded, regardless of whether they are generic or
--- language-specific, they persist in Textadept's Lua State; they are never
--- unloaded. Therefore, modules should not set global functions or variables in
--- order to avoid polluting the global environment. All functions and variables
--- should be contained within the module.
+-- Loaded modules, regardless of whether they are generic or language-specific,
+-- persist in Textadept's Lua State; Textadept never unloads them. Therefore,
+-- modules should define functions or variables within the module itself, not
+-- globally.
 --
 -- ### Language-Specific
 --
 -- To fully take advantage of Textadept's features, language-specific modules
 -- should have at a minimum: a block comment string, run and/or compile
--- commands, a buffer property setter function, and if possible, an Adeptsense.
--- Optional features are extra snippets and commands and a context menu.
+-- commands, an event handler for setting buffer properties like indentation,
+-- and if possible, an Adeptsense. Optional features are extra snippets and
+-- commands and a context menu.
 --
 -- #### Block Comment
 --
@@ -51,8 +51,7 @@
 --
 -- The module should also define error details in
 -- [`_M.textadept.run.error_detail`][] so double-clicking on compile or runtime
--- errors will jump to the error's location. The format for Lua errors looks
--- like
+-- errors jumps to the error's location. The format for Lua errors looks like
 --
 --     _M.textadept.run.error_detail.lua = {
 --       pattern = '^lua: (.-):(%d+): (.+)$',
@@ -89,7 +88,7 @@
 --
 -- #### Snippets
 --
--- [Snippets][] for common language constructs can be useful. Some snippets for
+-- [Snippets][] for common language constructs are useful. Some snippets for
 -- common Lua control structures look like
 --
 --     snippets.lua = {
@@ -109,23 +108,15 @@
 -- the current line and insert a new line. Both are bound to the `Shift+Enter`
 -- (`⇧↩` on Mac OSX | `S-Enter` in curses) key for easy access.
 --
---     function M.try_to_autocomplete_end()
---       ...
---     end
---
---     keys.lua = {
---       ['s\n'] = M.try_to_autocomplete_end
---     }
---
--- ---
---
---     keys.cpp = {
---       ['s\n'] = function()
---         buffer:line_end()
---         buffer:add_text(';')
---         buffer:new_line()
---       end
---     }
+--     -- In file *lua/init.lua*             | -- In file *cpp/init.lua*
+--                                           |
+--     function M.try_to_autocomplete_end()  | keys.cpp = {
+--       ...                                 |   ['s\n'] = function()
+--     end                                   |     buffer:line_end()
+--                                           |     buffer:add_text(';')
+--     keys.lua = {                          |     buffer:new_line()
+--       ['s\n'] = M.try_to_autocomplete_end |   end
+--     }                                     | }
 --
 -- [Lua]: _M.lua.html
 -- [C/C++]: _M.cpp.html
@@ -133,8 +124,8 @@
 -- #### Context Menu
 --
 -- Language-specific [context menus][], accessible by right-clicking inside the
--- view, can be useful for accessing module features without using key bindings.
--- For Lua this may look like
+-- view, are useful for accessing module features without using key bindings.
+-- For Lua this might look like
 --
 --     M.context_menu = {
 --       { _L['_Undo'], buffer.undo },
diff --git a/core/events.lua b/core/events.lua
index 02bb81b2..ee058d5b 100644
--- a/core/events.lua
+++ b/core/events.lua
@@ -8,20 +8,25 @@ local M = {}
 --
 -- ## Overview
 --
--- Events occur when you do things like create a new buffer, press a key, click
--- on a menu, etc. You can even emit events yourself using Lua. Each event has a
--- set of event handlers, which are simply Lua functions called in the order
--- they were connected to an event. This enables dynamically loaded modules to
--- connect to events.
+-- Textadept emits events when you do things like create a new buffer, press a
+-- key, click on a menu, etc. You can even emit events yourself using Lua. Each
+-- event has a set of event handlers, which are simply Lua functions called in
+-- the order they were connected to an event. For example, if you created a
+-- module that needs to do something each time Textadept creates a new buffer,
+-- connect a Lua function to the [BUFFER_NEW](#BUFFER_NEW) event:
 --
--- Events themselves are nothing special. They do not have to be declared in
--- order to be used. They are simply strings containing an arbitrary event name.
--- When an event of this name is emitted, either by Textadept or you, all event
--- handlers assigned to it are run. Events can be given any number of arguments.
--- These arguments will be passed to the event's handler functions. If an event
--- handler returns a `true` or `false` boolean value explicitly, no subsequent
--- handlers are called. This is useful if you want to stop the propagation of an
--- event like a keypress if it has already been handled.
+--     events.connect(events.BUFFER_NEW, function()
+--       -- Do something here.
+--     end)
+--
+-- Events themselves are nothing special. You do not have to declare one before
+-- using it. Events are simply strings containing arbitrary event names. When
+-- either you or Textadept emits an event, Textadept runs all event handlers
+-- connected to the event, passing any given arguments to the event's handler
+-- functions. If an event handler explicitly returns a `true` or `false` boolean
+-- value, Textadept will not call subsequent handlers. This is useful if you
+-- want to stop the propagation of an event like a keypress if your event
+-- handler handled it.
 --
 -- @field APPLEEVENT_ODOC (string)
 --   Emitted when Mac OSX tells Textadept to open a document.
diff --git a/core/file_io.lua b/core/file_io.lua
index 7dd0e354..24fa4a8a 100644
--- a/core/file_io.lua
+++ b/core/file_io.lua
@@ -6,22 +6,26 @@
 --
 -- ## Working with UTF-8
 --
--- If your filesystem does not use UTF-8-encoded filenames (e.g. Windows),
--- conversions to and from that encoding are necessary since all of Textadept's
--- internal strings are UTF-8-encoded. When opening and saving files through
--- dialogs, these conversions are performed automatically, but if you need to do
--- them manually, use [`string.iconv()`][] along with [`_CHARSET`][], your
--- filesystem's detected encoding. An example is
+-- Textadept encodes all of its filenames, like [`buffer.filename`][], in UTF-8.
+-- If you try to use Lua to access the file associated with such a filename, you
+-- may not get the right file if your filesystem's encoding is not UTF-8 (e.g.
+-- Windows).
 --
--- <div style="clear: right;"><!-- Clear Table of Contents --></div>
+--     -- May not work on non-UTF-8 filesystems.
+--     local f = io.open(buffer.filename, 'rb')
 --
---     events.connect(events.FILE_OPENED, function(utf8_filename)
---       local filename = utf8_filename:iconv(_CHARSET, 'UTF-8')
---       local f = io.open(filename, 'rb')
---       -- process file
---       f:close()
---     end)
+-- You need to convert the filename to the filesystem's encoding using
+-- [`string.iconv()`][] along with [`_CHARSET`][]:
 --
+--     local name = string.iconv(buffer.filename,
+--                               _CHARSET, 'UTF-8')
+--     local f = io.open(name, 'rb')
+--
+-- Textadept automatically performs filename conversions for you when opening
+-- and saving files through dialogs. You only need to do manual conversions when
+-- working with the filesystem directly from Lua.
+--
+-- [`buffer.filename`]: buffer.html#filename
 -- [`string.iconv()`]: string.html#iconv
 -- [`_CHARSET`]: _G.html#_CHARSET
 -- @field _G.events.FILE_OPENED (string)
diff --git a/core/keys.lua b/core/keys.lua
index 60f404a3..fc25b69a 100644
--- a/core/keys.lua
+++ b/core/keys.lua
@@ -8,21 +8,21 @@ local M = {}
 --
 -- ## Overview
 --
--- Key bindings are defined in the global table `keys`. Each key-value pair in
--- `keys` consists of either a string key sequence and its associated command,
--- a string lexer language (from the *lexers/* directory) with a table of key
--- sequences and commands, a string key mode with a table of key sequences and
--- commands, or a key sequence with a table of more sequences and commands. The
--- latter is part of what is called a "key chain", to be discussed below. When
--- searching for a command to run based on a key sequence, key bindings in the
--- current key mode have priority. If no key mode is active, key bindings in the
--- current lexer have priority, followed by the ones in the global table. This
--- means if there are two commands with the same key sequence, the one specific
--- to the current lexer is run. However, if the command returns the boolean
--- value `false`, the lower-priority command is also run. (This is useful for
--- language-specific modules to override commands like Adeptsense
--- autocompletion, but fall back to word autocompletion if the first command
--- fails.)
+-- Define key bindings in the global `keys` table in key-value pairs. Each pair
+-- consists of either a string key sequence and its associated command, a string
+-- lexer language (from the *lexers/* directory) with a table of key sequences
+-- and commands, a string key mode with a table of key sequences and commands,
+-- or a key sequence with a table of more sequences and commands. The latter is
+-- part of what is called a "key chain", to be discussed below. When searching
+-- for a command to run based on a key sequence, Textadept considers key
+-- bindings in the current key mode to have priority. If no key mode is active,
+-- key bindings in the current lexer have priority, followed by the ones in the
+-- global table. This means if there are two commands with the same key
+-- sequence, Textadept runs the one specific to the current lexer. However, if
+-- the command returns the boolean value `false`, Textadept also runs the
+-- lower-priority command. (This is useful for language-specific modules to
+-- override commands like Adeptsense autocompletion, but fall back to word
+-- autocompletion if the first command fails.)
 --
 -- ## Key Sequences
 --
@@ -39,24 +39,23 @@ local M = {}
 -- Shift    | `'s'`         | `'s'`   | `'s'`    |
 -- Command  | N/A           | `'c'`   | N/A      |
 --
--- For key values less than 255, their string representation is the character
--- that would normally be inserted if the "Control", "Alt", and "Command"
+-- The string representation of key values less than 255 is the character that
+-- Textadept would normally insert if the "Control", "Alt", and "Command"
 -- modifiers were not held down. Therefore, a combination of `Ctrl+Alt+Shift+A`
 -- has the key sequence `caA` on Windows and Linux, but a combination of
 -- `Ctrl+Shift+Tab` has the key sequence `cs\t`. On a United States English
 -- keyboard, since the combination of `Ctrl+Shift+,` has the key sequence `c<`
--- (`Shift+,` inserts a `<`), the key binding is referred to as `Ctrl+<`. This
--- allows key bindings to be language and layout agnostic. For key values
--- greater than 255, the [`KEYSYMS`](#KEYSYMS) lookup table is used. Therefore,
--- `Ctrl+Right Arrow` has the key sequence `cright`. Uncommenting the `print()`
--- statements in *core/keys.lua* will print key sequences to standard out
--- (stdout) for inspection.
+-- (`Shift+,` inserts a `<`), Textadept recognizes the key binding as `Ctrl+<`.
+-- This allows key bindings to be language and layout agnostic. For key values
+-- greater than 255, Textadept uses the [`KEYSYMS`](#KEYSYMS) lookup table.
+-- Therefore, `Ctrl+Right Arrow` has the key sequence `cright`. Uncommenting the
+-- `print()` statements in *core/keys.lua* causes Textadept to print key
+-- sequences to standard out (stdout) for inspection.
 --
 -- ## Commands
 --
--- Commands bound to key sequences can be either Lua functions, or tables
--- containing Lua functions with a set of arguments to call the function with.
--- Examples are:
+-- A command bound to a key sequence is either a Lua function or a table
+-- containing a Lua function with a set of arguments to pass. Examples are:
 --
 --     keys['cn'] = buffer.new
 --     keys['cs'] = buffer.save
@@ -66,15 +65,15 @@ local M = {}
 -- (The function and function table syntax are functionally equivalent. You can
 -- use either.)
 --
--- [`buffer`][] references are handled properly in static contexts.
+-- Textadept handles [`buffer`][] references properly in static contexts.
 --
 -- [`buffer`]: buffer.html
 --
 -- ## Modes
 --
--- Sets of key bindings can be grouped together into modes. When a key
--- [mode](#MODE) is active, all key bindings defined outside the mode are
--- ignored until the mode is unset. Here is a simple vi mode example:
+-- You can group together sets of key bindings into modes. When a key
+-- [mode](#MODE) is active, Textadept ignores all key bindings defined outside
+-- the mode until the mode is unset. Here is a simple vi mode example:
 --
 --     keys.command_mode = {
 --       ['h'] = buffer.char_left,
@@ -95,11 +94,11 @@ local M = {}
 --
 -- ## Key Chains
 --
--- Key chains are a powerful concept. They allow multiple key bindings to be
--- assigned to one key sequence. Language-specific modules
+-- Key chains are a powerful concept. They allow you to assign multiple key
+-- bindings to one key sequence. Language-specific modules
 -- [use key chains](#LANGUAGE_MODULE_PREFIX) for their functions. By default,
--- the `Esc` (`⎋` on Mac OSX | `Esc` in curses) key cancels a key chain, but it
--- can be redefined via [`CLEAR`](#CLEAR). An example key chain looks like:
+-- the `Esc` (`⎋` on Mac OSX | `Esc` in curses) key cancels a key chain, but you
+-- can redefine it via [`CLEAR`](#CLEAR). An example key chain looks like:
 --
 --     keys['aa'] = {
 --       a = function1,
diff --git a/modules/textadept/adeptsense.lua b/modules/textadept/adeptsense.lua
index 55c0effc..f0e7a320 100644
--- a/modules/textadept/adeptsense.lua
+++ b/modules/textadept/adeptsense.lua
@@ -11,27 +11,26 @@ local M = {}
 -- Adeptsense is a form of autocompletion for programming. It has the means to
 -- supply a list of potential completions for classes, member functions and
 -- fields, packages, etc and display their documentation in the form of a
--- calltip. This document provides the information necessary in order to write a
--- new Adeptsense for a language. For illustrative purposes, an Adeptsense for
--- Lua will be created. More advanced techniques are covered later.
+-- calltip. This document provides the information necessary to write a new
+-- Adeptsense for a language and demonstrates how to create an Adeptsense for
+-- Lua. The document covers more advanced techniques later.
 --
 -- ## Creating an Adeptsense
 --
--- Adeptsenses exist per-language and are typically defined in a
--- [language-specific module][]. First check to see if the module for your
+-- Adeptsenses exist per-language so they should be defined in
+-- [language-specific modules][]. First check to see if the module for your
 -- language has an Adeptsense. If not, you will need to create one. The language
--- modules included with Textadept have Adeptsenses so they can be used for
--- reference. If your language is similar to any of those languages, you can
--- copy and modify the existing language's Adeptsense, saving some time and
--- effort.
+-- modules included with Textadept have Adeptsenses and are useful references.
+-- If your language is similar to any of those languages, you can copy and
+-- modify the existing language's Adeptsense, saving some time and effort.
 --
--- [language-specific module]: _M.html#Language-Specific.Modules
+-- [language-specific modules]: _M.html#Language-Specific.Modules
 --
 -- ### Terminology
 --
 -- Not all languages have "classes", "functions", and "fields" in the full sense
--- of the word. Normally classes are referred to as objects in Object Oriented
--- Programming (OOP), functions are class or instance methods,and fields are
+-- of the word. Object Oriented Programming (OOP) normally refers to classes as
+-- objects with functions being class or instance methods, and fields being
 -- class or instance properties. For example a "Cat" class may have a "color"
 -- field and a "meow" function. To Adeptsense, the term "class" is simply a
 -- container for "function" and "field" completions. "functions" and "fields"
@@ -51,7 +50,7 @@ local M = {}
 --
 --     sense = _M.textadept.adeptsense.new('lua')
 --
--- Where 'lua' is replaced by your language's name.
+-- replacing 'lua' with your language's name.
 --
 -- ### Syntax Options
 --
@@ -62,8 +61,8 @@ local M = {}
 -- #### `self`
 --
 -- The first syntax option is `syntax.self`. While Lua has a `self` identifier,
--- it is not used in the usual sense for a class instance so it will just be
--- ignored.
+-- Lua does not use that identifier in the usual sense for a class instance so
+-- it is ignored.
 --
 -- #### `class_definition`
 --
diff --git a/modules/textadept/command_entry.lua b/modules/textadept/command_entry.lua
index dab02e2b..45dd7d3c 100644
--- a/modules/textadept/command_entry.lua
+++ b/modules/textadept/command_entry.lua
@@ -12,9 +12,9 @@ local M = gui.command_entry
 -- The command entry supports multiple [modes][] that have their own sets of key
 -- bindings stored in a separate table in `_G.keys` under a mode prefix key.
 -- Mode names are arbitrary, but cannot conflict with lexer names or key
--- sequence strings (e.g. `'lua'` or `'send'`) due to the method used for
--- looking up key bindings. An example mode is "lua_command" mode for executing
--- Lua commands:
+-- sequence strings (e.g. `'lua'` or `'send'`) due to the method Textadept uses
+-- for looking up key bindings. An example mode is "lua_command" mode for
+-- executing Lua commands:
 --
 --     local gui_ce = gui.command_entry
 --     keys['ce'] = {gui_ce.enter_mode, 'lua_command'}
@@ -25,15 +25,10 @@ local M = gui.command_entry
 --
 -- In this case, `Ctrl+E` opens the command entry and enters "lua_command" key
 -- mode where the `Tab` and `Enter` keys have special, defined functionality.
--- (By default, `Esc` is pre-defined to exit any command entry mode.) `Tab`
--- shows a list of Lua completions for the entry text and `Enter` exits
--- "lua_command" key mode and executes the entered code. All other keys are
--- handled normally by the command entry.
---
--- It is important to note that while in any command entry key mode, all editor
--- key bindings are ignored -- even if the editor, not the command entry, has
--- focus. You must first exit the key mode by pressing `Esc` (or `Enter` in the
--- case of the above "lua_command" key mode).
+-- (By default, Textadept pre-defines `Esc` to exit any command entry mode.)
+-- `Tab` shows a list of Lua completions for the entry text and `Enter` exits
+-- "lua_command" key mode and executes the entered code. The command entry
+-- handles all other keys normally.
 --
 -- [modes]: keys.html#Modes
 -- @field entry_text (string)
diff --git a/modules/textadept/snippets.lua b/modules/textadept/snippets.lua
index 05324a25..00e46f47 100644
--- a/modules/textadept/snippets.lua
+++ b/modules/textadept/snippets.lua
@@ -8,32 +8,31 @@ local M = {}
 --
 -- ## Overview
 --
--- Snippets are defined in the global table `snippets`. Each key-value pair in
--- `snippets` consists of either a string trigger word and its snippet text, or
--- a string lexer language (from the *lexers/* directory) with a table of
--- trigger words and snippet texts. When searching for a snippet to insert based
--- on a trigger word, snippets in the current lexer have priority, followed by
--- the ones in the global table. This means if there are two snippets with the
--- same trigger word, the one specific to the current lexer is inserted, not the
--- global one.
+-- Define snippets in the global `snippets` table in key-value pairs. Each pair
+-- consists of either a string trigger word and its snippet text, or a string
+-- lexer language (from the *lexers/* directory) with a table of trigger words
+-- and snippet texts. When searching for a snippet to insert based on a trigger
+-- word, Textadept considers snippets in the current lexer to have priority,
+-- followed by the ones in the global table. This means if there are two
+-- snippets with the same trigger word, Textadept inserts the one specific to
+-- the current lexer, not the global one.
 --
 -- ## Snippet Syntax
 --
--- Any plain text characters may be used with the exception of '%'. Just like in
--- Lua patterns, '%' is an escape character. The sequence "%%" stands for a
--- single '%'. Also, it is recommended to use "\t" characters for indentation
--- because they can be converted to spaces based on the current indentation
--- settings. In addition to plain text, snippets can contain placeholders for
--- further user input, can mirror or transform those user inputs, and/or execute
--- arbitrary code.
+-- You may use any plain text characters except '%' in snippet text. Just like
+-- in Lua patterns, '%' is an escape character. The sequence "%%" stands for a
+-- single '%'. Also, try to use "\t" characters for indentation so Textadept can
+-- make the necessary conversions to respect the user's indentation preference.
+-- Using the '%' sequences described below, you can define placeholders,
+-- mirrors, and transforms for user input.
 --
 -- ### Placeholders
 --
--- `%`_`n`_`(`_`text`_`)` sequences are called placeholders, where _`n`_ is an
--- integer and _`text`_ is the default text inserted into the placeholder.
--- Placeholders are visited in numeric order each time [`_insert()`](#_insert)
--- is called with an active snippet. When no more placeholders are left, the
--- caret is placed at the `%0` placeholder (if it exists), or at the end of the
+-- Textadept calls `%`_`n`_`(`_`text`_`)` sequences, where _`n`_ is an integer,
+-- placeholders. The editor visits placeholders in numeric order each time it
+-- calls [`_insert()`](#_insert) and inserts the default text _`text`_ into the
+-- placeholder. When there are no more placeholders left, Textadept places the
+-- caret at either the `%0` placeholder if it exists or at the end of the
 -- snippet. Examples are
 --
 --     snippets['foo'] = 'foobar%1(baz)'
@@ -41,8 +40,8 @@ local M = {}
 --
 -- ### Mirrors
 --
--- `%`_`n`_ sequences are called mirrors, where _`n`_ is an integer. Mirrors
--- with the same _`n`_ as a placeholder mirror any user input in the
+-- Textadept calls `%`_`n`_ sequences, where _`n`_ is an integer, mirrors.
+-- Mirrors with the same _`n`_ as a placeholder mirror any user input in the
 -- placeholder. If no placeholder exists for _`n`_, the first occurrence of that
 -- mirror in the snippet becomes the placeholder, but with no default text.
 -- Examples are
@@ -52,24 +51,24 @@ local M = {}
 --
 -- ### Transforms
 --
--- `%`_`n`_`<`_`Lua code`_`>` and `%`_`n`_`[`_`Shell code`_`]` sequences are
--- called transforms, where _`n`_ is an integer,  _`Lua code`_ is arbitrary Lua
--- code, and _`Shell code`_ is arbitrary Shell code. The _`n`_ is optional, and
--- for transforms that omit it, their code is executed the moment the snippet is
--- inserted. Otherwise, the code is executed as placeholders are visited.
+-- Textadept calls `%`_`n`_`<`_`Lua code`_`>` and `%`_`n`_`[`_`Shell code`_`]`
+-- sequences, where _`n`_ is an integer, transforms. _`Lua code`_ is arbitrary
+-- Lua code and _`Shell code`_ is arbitrary Shell code. Textadept executes the
+-- code when the editor visits placeholder _`n`_. If the transform omits _`n`_,
+-- Textadept executes the transform's code the moment the editor inserts the
+-- snippet.
 --
--- Lua code is run in Textadept's Lua State with with an additional
--- `selected_text` global variable that contains the current selection in the
--- buffer. The transform is replaced with the return value of the executed code.
--- An example is
+-- Textadept runs Lua code in its Lua State and replaces the transform with the
+-- code's return text. The code may use a temporary `selected_text` global
+-- variable that contains the current selection in the buffer. An example is
 --
 --     snippets['foo'] = [[
 --     %2<('%1'):gsub('^.', function(c)
 --       return c:upper() -- capitalize the word
 --     end)>, %1(mirror) on the wall.]]
 --
--- Shell code is executed using Lua's [`io.popen()`][]. The transform is
--- replaced with the process' standard output (stdout). An example is
+-- Textadept executes shell code using Lua's [`io.popen()`][] and replaces the
+-- transform with the process' standard output (stdout). An example is
 --
 --     snippets['foo'] = '$%1(HOME) = %2[echo $%1]'
 --