Rewrote some LuaDoc to use the active voice.

3 files changed, 53 insertions, 60 deletions

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]'
 --