From d6b32bf2bd4a94a3fe7b70719a8f91061fd9a3f6 Mon Sep 17 00:00:00 2001
From: mitchell <70453897+667e-11@users.noreply.github.com>
Date: Sun, 26 May 2013 16:14:10 -0400
Subject: Rewrote some LuaDoc to use the active voice.

---
 core/._M.luadoc | 51 +++++++++++++++++++++------------------------------
 1 file changed, 21 insertions(+), 30 deletions(-)

(limited to 'core/._M.luadoc')

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 },
-- 
cgit v1.2.3