13 files changed, 79 insertions, 101 deletions
diff --git a/modules/textadept/adeptsense.lua b/modules/textadept/adeptsense.lua
index b1004fd2..7e3d7449 100644
--- a/modules/textadept/adeptsense.lua
+++ b/modules/textadept/adeptsense.lua
@@ -5,9 +5,7 @@ local M = {}
 --[[ This comment is for LuaDoc.
 ---
 -- Language autocompletion support for the textadept module.
-module('_M.textadept.adeptsense')]]
-
--- Markdown:
+--
 -- ## Overview
 --
 -- Adeptsense is a form of autocompletion for programming. It has the means to
@@ -142,7 +140,7 @@ module('_M.textadept.adeptsense')]]
 -- in your shell. Since Adeptsense only cares about classes, functions, and
 -- fields, you need to let it know which kind of tag is which. Unfortunately,
 -- Lua support in Ctags is not good at all. Instead, Textadept has a utility
--- (`scripts/adeptsensedoc.lua`) to generate a fake set of tags that is more
+-- (`modules/lua/adeptsensedoc.lua`) to generate a fake set of tags that is more
 -- useful. Functions are tagged `'f'` and should be recognized as such; table
 -- keys are tagged `'t'` and should be recognized as fields; module fields,
 -- `'F'`, should be fields; and modules, `'m'`, should be classes:
@@ -201,7 +199,7 @@ module('_M.textadept.adeptsense')]]
 -- characters for an Adeptsense is sufficient for most static and some dynamic
 -- languages. The rest of this document is devoted to more complex techniques.
 --
--- ### Overriding Adeptsense Functions
+-- ### Fine-Tuning
 --
 -- Sometimes Adeptsense's default behavior is not sufficient. Maybe the
 -- `type_declarations` and `type_assignments` tables used by the
@@ -343,22 +341,16 @@ module('_M.textadept.adeptsense')]]
 -- [`load_ctags()`](#load_ctags) and [`api_files`](#api_files) respectively.
 --
 -- [LuaDoc]: http://keplerproject.github.com/luadoc/
---
--- ### Other Adeptsense Settings
---
--- * `always_show_globals` [bool]
+-- @field always_show_globals (bool)
 --   Include globals in the list of completions offered.
 --   Globals are classes, functions, and fields that do not belong to another
 --   class. They are contained in `completions['']`. The default value is
 --   `true`.
-
---
--- ## Settings
---
--- * `FUNCTIONS` [string]
+-- @field FUNCTIONS (string)
 --   XPM image for Adeptsense functions.
--- * `FIELDS` [string]
+-- @field FIELDS (string)
 --   XPM image for Adeptsense fields.
+module('_M.textadept.adeptsense')]]
 
 local senses = {}
 
diff --git a/modules/textadept/bookmarks.lua b/modules/textadept/bookmarks.lua
index 33fcf0e9..4219da58 100644
--- a/modules/textadept/bookmarks.lua
+++ b/modules/textadept/bookmarks.lua
@@ -5,13 +5,9 @@ local M = {}
 --[[ This comment is for LuaDoc.
 ---
 -- Bookmarks for the textadept module.
-module('_M.textadept.bookmarks')]]
-
--- Markdown:
--- ## Settings
---
--- * `MARK_BOOKMARK_COLOR` [number]
+-- @field MARK_BOOKMARK_COLOR (number)
 --   The color used for a bookmarked line in `0xBBGGRR` format.
+module('_M.textadept.bookmarks')]]
 
 M.MARK_BOOKMARK_COLOR = 0xB3661A
 
diff --git a/modules/textadept/command_entry.lua b/modules/textadept/command_entry.lua
index 5483ffa9..0ae836c4 100644
--- a/modules/textadept/command_entry.lua
+++ b/modules/textadept/command_entry.lua
@@ -4,13 +4,9 @@
 --[[ This comment is for LuaDoc.
 ---
 -- Textadept's Command entry.
-module('gui.command_entry')]]
-
--- Markdown:
--- ## Fields
---
--- * `entry_text` [string]
+-- @field entry_text (string)
 --   The text in the entry.
+module('gui.command_entry')]]
 
 -- Environment for abbreviated commands.
 -- @class table
diff --git a/modules/textadept/editing.lua b/modules/textadept/editing.lua
index 9093a150..6dfea6b7 100644
--- a/modules/textadept/editing.lua
+++ b/modules/textadept/editing.lua
@@ -5,34 +5,30 @@ local M = {}
 --[[ This comment is for LuaDoc.
 ---
 -- Editing commands for the textadept module.
-module('_M.textadept.editing')]]
-
--- Markdown:
--- ## Settings
---
--- * `AUTOPAIR` [bool]
+-- @field AUTOPAIR (bool)
 --   Opening `(`, `[`, `[`, `"`, or `'` characters are automatically closed.
 --   The default value is `true`.
--- * `HIGHLIGHT_BRACES` [bool]
---   Highlight matching `()[]{}<>` characters.
+-- @field HIGHLIGHT_BRACES (bool)
+--   Highlight matching `()[]{}` characters.
 --   The default value is `true`.
--- * `AUTOINDENT` [bool]
+-- @field AUTOINDENT (bool)
 --   Match the indentation level of the previous line when pressing the Enter
 --   key.
 --   The default value is `true`.
--- * `STRIP_WHITESPACE_ON_SAVE` [bool]
+-- @field STRIP_WHITESPACE_ON_SAVE (bool)
 --   Strip trailing whitespace on file save.
 --   The default value is `true`.
--- * `MARK_HIGHLIGHT_BACK` [number]
+-- @field MARK_HIGHLIGHT_BACK (number)
 --   The background color used for a line containing a highlighted word in
 --   `0xBBGGRR` format.
--- * `INDIC_HIGHLIGHT_BACK` [number]
+-- @field INDIC_HIGHLIGHT_BACK (number)
 --   The color used for an indicator for a highlighted word in `0xBBGGRR`
 --   format.
--- * `INDIC_HIGHLIGHT_ALPHA` [number]
+-- @field INDIC_HIGHLIGHT_ALPHA (number)
 --   The alpha transparency value between `0` (transparent) and `255` (opaque)
 --   used for an indicator for a highlighted word.
 --   The default value is `100`.
+module('_M.textadept.editing')]]
 
 M.AUTOPAIR = true
 M.HIGHLIGHT_BRACES = true
@@ -44,7 +40,7 @@ M.INDIC_HIGHLIGHT_ALPHA = 100
 
 ---
 -- Comment strings for various lexer languages.
--- Used for the `block_comment()` function. Keys are lexer language names and
+-- Used by the `block_comment()` function. Keys are lexer language names and
 -- values are the line comment delimiters for the language. This table is
 -- typically populated by language-specific modules.
 -- @class table
@@ -61,6 +57,7 @@ M.comment_string = {}
 -- @class table
 -- @name char_matches
 -- @usage _M.textadept.editing.char_matches.hypertext = { ..., [60] = '>' }
+-- @see AUTOPAIR
 M.char_matches = { [40] = ')', [91] = ']', [123] = '}', [39] = "'", [34] = '"' }
 
 ---
@@ -71,6 +68,7 @@ M.char_matches = { [40] = ')', [91] = ']', [123] = '}', [39] = "'", [34] = '"' }
 -- @class table
 -- @name braces
 -- @usage _M.textadept.editing.braces.hypertext = { ..., [60] = 1, [62] = 1 }
+-- @see HIGHLIGHT_BRACES
 M.braces = { [40] = 1, [41] = 1, [91] = 1, [93] = 1, [123] = 1, [125] = 1 }
 
 -- The current call tip.
@@ -232,8 +230,10 @@ end
 
 ---
 -- Block comments or uncomments code with a given comment string.
+-- If none is specified, uses the `comment_string` table.
 -- @param comment The comment string inserted or removed from the beginning of
 --   each line in the selection.
+-- @see comment_string
 -- @name block_comment
 function M.block_comment(comment)
   local buffer = buffer
@@ -281,8 +281,9 @@ end
 
 ---
 -- Prepares the buffer for saving to a file.
--- Strips trailing whitespace off of every line, ensures an ending newline, and
--- converts non-consistent EOLs.
+-- Strips trailing whitespace off of every line if `STRIP_WHITESPACE_ON_SAVE` is
+-- `true`, ensures an ending newline, and converts non-consistent EOLs.
+-- @see STRIP_WHITESPACE_ON_SAVE
 -- @name prepare_for_save
 function M.prepare_for_save()
   if not M.STRIP_WHITESPACE_ON_SAVE then return end
@@ -386,7 +387,7 @@ end
 ---
 -- Selects the current word under the caret.
 -- @name select_word
-function M.select_word(action)
+function M.select_word()
   local buffer = buffer
   buffer:set_sel(buffer:word_start_position(buffer.current_pos, true),
                  buffer:word_end_position(buffer.current_pos, true))
diff --git a/modules/textadept/filter_through.lua b/modules/textadept/filter_through.lua
index 3c43a131..0e6a0fc0 100644
--- a/modules/textadept/filter_through.lua
+++ b/modules/textadept/filter_through.lua
@@ -14,13 +14,16 @@ local filter_through_active = false
 ---
 -- Prompts for a Linux, Mac OSX, or Windows shell command to filter text
 -- through.
--- The standard input (stdin) for shell commands is determined as follows: (1)
--- If text is selected and spans multiple lines, all text on the lines
+-- The standard input (stdin) for shell commands is determined as follows:
+--
+-- 1. If text is selected and spans multiple lines, all text on the lines
 -- containing the selection is used. However, if the end of the selection is at
 -- the beginning of a line, only the EOL (end of line) characters from the
--- previous line are included as input. 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.
+-- previous line are included as input. 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.
+--
 -- The input text is replaced with the standard output (stdout) of the command.
 -- @name filter_through
 function M.filter_through()
diff --git a/modules/textadept/find.lua b/modules/textadept/find.lua
index 8e6ef20f..62fbc5fe 100644
--- a/modules/textadept/find.lua
+++ b/modules/textadept/find.lua
@@ -5,53 +5,49 @@ local find = gui.find
 --[[ This comment is for LuaDoc.
 ---
 -- Textadept's integrated find/replace dialog.
-module('gui.find')]]
-
--- Markdown:
--- ## Fields
---
--- * `find_entry_text` [string]
+-- @field find_entry_text (string)
 --   The text in the find entry.
--- * `replace_entry_text` [string]
+-- @field replace_entry_text (string)
 --   The text in the replace entry.
--- * `match_case` [bool]
+-- @field match_case (bool)
 --   Searches are case-sensitive.
--- * `whole_word` [bool]
+-- @field whole_word (bool)
 --   Only whole-word matches are allowed in searches.
--- * `lua` [bool]
+-- @field lua (bool)
 --   The search text is interpreted as a Lua pattern.
--- * `in_files` [bool]
+-- @field in_files (bool)
 --   Search for the text in a list of files.
--- * `find_label_text` [string] (Write-only)
+-- @field find_label_text (string, Write-only)
 --   The text of the 'Find' label.
 --   This is primarily used for localization.
--- * `replace_label_text` [string] (Write-only)
+-- @field replace_label_text (string, Write-only)
 --   The text of the 'Replace' label.
 --   This is primarily used for localization.
--- * `find_next_button_text` [string] (Write-only)
+-- @field find_next_button_text (string, Write-only)
 --   The text of the 'Find Next' button.
 --   This is primarily used for localization.
--- * `find_prev_button_text` [string] (Write-only)
+-- @field find_prev_button_text (string, Write-only)
 --   The text of the 'Find Prev' button.
 --   This is primarily used for localization.
--- * `replace_button_text` [string] (Write-only)
+-- @field replace_button_text (string, Write-only)
 --   The text of the 'Replace' button.
 --   This is primarily used for localization.
--- * `replace_all_button_text` [string] (Write-only)
+-- @field replace_all_button_text (string, Write-only)
 --   The text of the 'Replace All' button.
 --   This is primarily used for localization.
--- * `match_case_label_text` [string] (Write-only)
+-- @field match_case_label_text (string, Write-only)
 --   The text of the 'Match case' label.
 --   This is primarily used for localization.
--- * `whole_word_label_text` [string] (Write-only)
+-- @field whole_word_label_text (string, Write-only)
 --   The text of the 'Whole word' label.
 --   This is primarily used for localization.
--- * `lua_pattern_label_text` [string] (Write-only)
+-- @field lua_pattern_label_text (string, Write-only)
 --   The text of the 'Lua pattern' label.
 --   This is primarily used for localization.
--- * `in_files_label_text` [string] (Write-only)
+-- @field in_files_label_text (string, Write-only)
 --   The text of the 'In files' label.
 --   This is primarily used for localization.
+module('gui.find')]]
 
 local _L = _L
 find.find_label_text = _L['Find:']
diff --git a/modules/textadept/keys.lua b/modules/textadept/keys.lua
index 33ceb8e8..f2e8bf73 100644
--- a/modules/textadept/keys.lua
+++ b/modules/textadept/keys.lua
@@ -6,7 +6,7 @@ local M = {}
 ---
 -- Defines key commands for Textadept.
 -- This set of key commands is pretty standard among other text editors.
--- This module, should be `require`ed last, but before `_M.textadept.menu`.
+-- This module, should be `require`d last, but before `_M.textadept.menu`.
 module('_M.textadept.keys')]]
 
 -- Utility functions.
diff --git a/modules/textadept/menu.lua b/modules/textadept/menu.lua
index 967521a9..29a1a85a 100644
--- a/modules/textadept/menu.lua
+++ b/modules/textadept/menu.lua
@@ -6,7 +6,7 @@ local M = {}
 --[[ This comment is for LuaDoc.
 ---
 -- Provides dynamic menus for Textadept.
--- This module should be `require`ed last, after `_M.textadept.keys` since it
+-- This module should be `require`d last, after `_M.textadept.keys` since it
 -- looks up defined key commands to show them in menus.
 module('_M.textadept.menu')]]
 
@@ -279,6 +279,7 @@ end
 --   for setting a menu accelerator. If the menu text is `'separator'`, a menu
 --   separator is created and no action table is required.
 -- @see keys.get_gdk_key
+-- @see rebuild_command_tables
 -- @name set_menubar
 function M.set_menubar(menubar)
   key_shortcuts = {}
diff --git a/modules/textadept/mime_types.lua b/modules/textadept/mime_types.lua
index 1760f23d..9efbbec9 100644
--- a/modules/textadept/mime_types.lua
+++ b/modules/textadept/mime_types.lua
@@ -5,9 +5,7 @@ local M = {}
 --[[ This comment is for LuaDoc.
 ---
 -- Handles file-specific settings.
-module('_M.textadept.mime_types')]]
-
--- Markdown:
+--
 -- ## Mime-type Events
 --
 -- * `_G.events.LANGUAGE_MODULE_LOADED`
@@ -16,6 +14,7 @@ module('_M.textadept.mime_types')]]
 --   when Textadept starts.
 --   Arguments:
 --     * `lang`: The language lexer name.
+module('_M.textadept.mime_types')]]
 
 -- Events.
 local events, events_connect = events, events.connect
diff --git a/modules/textadept/run.lua b/modules/textadept/run.lua
index 42423c7b..b8af5f66 100644
--- a/modules/textadept/run.lua
+++ b/modules/textadept/run.lua
@@ -8,9 +8,7 @@ local M = {}
 -- Typically, language-specific modules populate the `compile_command`,
 -- `run_command`, and `error_detail` tables for a particular language's file
 -- extension.
-module('_M.textadept.run')]]
-
--- Markdown:
+--
 -- ## Run Events
 --
 -- * `_G.events.COMPILE_OUTPUT`
@@ -31,6 +29,7 @@ module('_M.textadept.run')]]
 --   Arguments:
 --     * `lexer`: The lexer language.
 --     * `output`: The output from the command.
+module('_M.textadept.run')]]
 
 -- Events.
 local events, events_connect, events_emit = events, events.connect, events.emit
diff --git a/modules/textadept/session.lua b/modules/textadept/session.lua
index 5dffaaf6..91adf795 100644
--- a/modules/textadept/session.lua
+++ b/modules/textadept/session.lua
@@ -5,21 +5,17 @@ local M = {}
 --[[ This comment is for LuaDoc.
 ---
 -- Session support for the textadept module.
-module('_M.textadept.session')]]
-
--- Markdown:
--- ## Settings
---
--- * `DEFAULT_SESSION` [string]
+-- @field DEFAULT_SESSION (string)
 --   The path to the default session file.
--- * `SAVE_ON_QUIT` [bool]
+-- @field SAVE_ON_QUIT (bool)
 --   Save the session when quitting.
 --   The default value is `true` and can be disabled by passing the command line
 --   switch `-n` or `--nosession` to Textadept.
--- * `MAX_RECENT_FILES` [number]
+-- @field MAX_RECENT_FILES (number)
 --   The maximum number of files from the recent files list to save to the
 --   session.
 --   The default value is `10`.
+module('_M.textadept.session')]]
 
 M.DEFAULT_SESSION = _USERHOME..'/session'
 M.SAVE_ON_QUIT = true
@@ -33,6 +29,7 @@ M.MAX_RECENT_FILES = 10
 --   value is `DEFAULT_SESSION`.
 -- @return `true` if the session file was opened and read; `false` otherwise.
 -- @usage _M.textadept.session.load(filename)
+-- @see DEFAULT_SESSION
 -- @name load
 function M.load(filename)
   local not_found = {}
@@ -112,6 +109,7 @@ events.connect('arg_none', function() if M.SAVE_ON_QUIT then M.load() end end)
 -- @param filename The absolute path to the session file to save. The default
 --   value is either the current session file or `DEFAULT_SESSION`.
 -- @usage _M.textadept.session.save(filename)
+-- @see DEFAULT_SESSION
 -- @name save
 function M.save(filename)
   local session = {}
diff --git a/modules/textadept/snapopen.lua b/modules/textadept/snapopen.lua
index 6f8d4772..3ccfe376 100644
--- a/modules/textadept/snapopen.lua
+++ b/modules/textadept/snapopen.lua
@@ -5,15 +5,6 @@ local M = {}
 --[[ This comment is for LuaDoc.
 ---
 -- Snapopen for the textadept module.
-module('_M.textadept.snapopen')]]
-
--- Markdown:
--- ## Settings
---
--- * `DEFAULT_DEPTH` [number]
---   Maximum directory depth to search. The default value is `4`.
--- * `MAX` [number]
---   Maximum number of files to list. The default value is `1000`.
 --
 -- ## Examples
 --
@@ -29,8 +20,15 @@ module('_M.textadept.snapopen')]]
 --     snapopen(nil, '!%.lua$')
 --
 --     -- Ignore the project's 'images' folder and HTML pages.
---     snapopen('/path/to/project',
---              { folders = { 'images' }, extensions = { 'html' } }, true)
+--     snapopen('/path/to/project', {
+--                folders = { 'images' },
+--                extensions = { 'html' }
+--              }, true)
+-- @field DEFAULT_DEPTH (number)
+--   Maximum directory depth to search. The default value is `4`.
+-- @field MAX (number)
+--   Maximum number of files to list. The default value is `1000`.
+module('_M.textadept.snapopen')]]
 
 ---
 -- Table of default UTF-8 paths to search.
diff --git a/modules/textadept/snippets.lua b/modules/textadept/snippets.lua
index 1647c3fe..3674a079 100644
--- a/modules/textadept/snippets.lua
+++ b/modules/textadept/snippets.lua
@@ -2,12 +2,10 @@
 
 local M = {}
 
---[[ This comment is for LuaDoc.
+--[=[ This comment is for LuaDoc.
 ---
 -- Provides Lua-style snippets for Textadept.
-module('_M.textadept.snippets')]]
-
--- Markdown:
+--
 -- ## Overview
 --
 -- Snippets are dynamic pieces of text inserted into a document that contain
@@ -117,6 +115,7 @@ module('_M.textadept.snippets')]]
 --
 -- It is recommended to use tab characters instead of spaces like in the last
 -- example. Tabs will be converted to spaces as necessary.
+module('_M.textadept.snippets')]=]
 
 -- The stack of currently running snippets.
 local snippet_stack = {}