Reformatted some LuaDoc.

10 files changed, 182 insertions, 179 deletions

diff --git a/modules/textadept/adeptsense.lua b/modules/textadept/adeptsense.lua
index 20dae39d..ee6fa1e9 100644
--- a/modules/textadept/adeptsense.lua
+++ b/modules/textadept/adeptsense.lua
@@ -212,7 +212,7 @@ module('_m.textadept.adeptsense', package.seeall)
 --       end
 --     end
 --
--- The default adeptsense functions are called by using the `self.super`
+-- The default Adeptsense functions are called by using the `self.super`
 -- reference.
 --
 -- ##### Examples for Ruby
@@ -319,8 +319,8 @@ module('_m.textadept.adeptsense', package.seeall)
 --
 -- ## Settings
 --
--- * `FUNCTIONS` [string]: XPM image for adeptsense functions.
--- * `FIELDS` [string]: XPM image for adeptsense fields.
+-- * `FUNCTIONS` [string]: XPM image for Adeptsense functions.
+-- * `FIELDS` [string]: XPM image for Adeptsense fields.
 
 local senses = {}
 
@@ -330,9 +330,9 @@ FIELDS = '/* XPM */\nstatic char *field[] = {\n/* columns rows colors chars-per-
 ---
 -- Returns a full symbol (if any) and current symbol part (if any) behind the
 -- caret.
--- For example: buffer.cur would return 'buffer' and 'cur'.
--- @param sense The adeptsense returned by adeptsense.new().
--- @return symbol or '', part or ''.
+-- For example: `buffer.cur` would return `'buffer'` and `'cur'`.
+-- @param sense The Adeptsense returned by `adeptsense.new()`.
+-- @return symbol or `''`, part or `''`.
 function get_symbol(sense)
   local line, p = buffer:get_cur_line()
   local sc, wc = sense.syntax.symbol_chars, sense.syntax.word_chars
@@ -344,13 +344,13 @@ end
 
 ---
 -- Returns the class name for a given symbol.
--- If the symbol is sense.syntax.self and a class definition using the
--- sense.syntax.class_definition keyword is found, that class is returned.
+-- If the symbol is `sense.syntax.self` and a class definition using the
+-- `sense.syntax.class_definition` keyword is found, that class is returned.
 -- Otherwise the buffer is searched backwards for a type declaration of the
--- symbol according to the patterns in sense.syntax.type_declarations.
--- @param sense The adeptsense returned by adeptsense.new().
+-- symbol according to the patterns in `sense.syntax.type_declarations`.
+-- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @param symbol The symbol to get the class of.
--- @return class or nil
+-- @return class or `nil`
 -- @see syntax
 function get_class(sense, symbol)
   local buffer = buffer
@@ -408,16 +408,16 @@ function get_class(sense, symbol)
 end
 
 -- Adds an inherited class's completions to the given completion list.
--- @param sense The adeptsense returned by adeptsense.new().
+-- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @param class The name of the class to add inherited completions from.
--- @param only_fields If true, adds only fields to the completion list; defaults
---   to false.
--- @param only_funcs If true, adds only functions to the completion list;
---   defaults to false.
+-- @param only_fields If `true`, adds only fields to the completion list;
+--   defaults to `false`.
+-- @param only_funcs If `true`, adds only functions to the completion list;
+--   defaults to `false`.
 -- @param c The completion list to add completions to.
 -- @param added Table that keeps track of what inherited classes have been
---   added. This prevents stack overflow errors. Should be {} on the initial
---   call to add_inherited().
+--   added. This prevents stack overflow errors. Should be `{}` on the initial
+--   call to `add_inherited()`.
 local function add_inherited(sense, class, only_fields, only_funcs, c, added)
   local inherited_classes = sense.inherited_classes[class]
   if not inherited_classes or added[class] then return end
@@ -439,12 +439,13 @@ end
 
 ---
 -- Returns a list of completions for the given symbol.
--- @param sense The adeptsense returned by adeptsense.new().
+-- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @param symbol The symbol to get completions for.
--- @param only_fields If true, returns list of only fields; defaults to false.
--- @param only_functions If true, returns list of only functions; defaults to
---   false.
--- @return completion_list or nil
+-- @param only_fields If `true`, returns list of only fields; defaults to
+--   `false`.
+-- @param only_functions If `true`, returns list of only functions; defaults to
+--   `false`.
+-- @return completion_list or `nil`
 function get_completions(sense, symbol, only_fields, only_functions)
   if only_fields and only_functions or not symbol then return nil end
   local compls = sense.completions
@@ -493,11 +494,12 @@ end
 
 ---
 -- Shows an autocompletion list for the symbol behind the caret.
--- @param sense The adeptsense returned by adeptsense.new().
--- @param only_fields If true, returns list of only fields; defaults to false.
--- @param only_functions If true, returns list of only functions; defaults to
---   false.
--- @return true on success or false.
+-- @param sense The Adeptsense returned by `adeptsense.new()`.
+-- @param only_fields If `true`, returns list of only fields; defaults to
+--   `false`.
+-- @param only_functions If `true`, returns list of only functions; defaults to
+--   `false1.
+-- @return `true` on success or `false`.
 -- @see get_symbol
 -- @see get_completions
 function complete(sense, only_fields, only_functions)
@@ -511,8 +513,8 @@ function complete(sense, only_fields, only_functions)
   if not buffer.auto_c_choose_single or #completions ~= 1 then
     buffer:auto_c_show(#part, table.concat(completions, ' '))
   else
-    -- Scintilla does not emit AUTO_C_SELECTION in this case. This is necessary
-    -- for autocompletion with multiple selections.
+    -- Scintilla does not emit `AUTO_C_SELECTION` in this case. This is
+    -- necessary for autocompletion with multiple selections.
     events.emit(events.AUTO_C_SELECTION, completions[1]:sub(#part + 1),
                 buffer.current_pos)
   end
@@ -521,13 +523,13 @@ end
 
 ---
 -- Sets the trigger for autocompletion.
--- @param sense The adeptsense returned by adeptsense.new().
+-- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @param c The character(s) that triggers the autocompletion. You can have up
 --   to two characters.
--- @param only_fields If true, this trigger only completes fields. Defaults to
---   false.
--- @param only_functions If true, this trigger only completes functions.
---   Defaults to false.
+-- @param only_fields If `true`, this trigger only completes fields. Defaults to
+--   `false`.
+-- @param only_functions If `true`, this trigger only completes functions.
+--   Defaults to `false`.
 -- @usage sense:add_trigger('.')
 -- @usage sense:add_trigger(':', false, true) -- only functions
 -- @usage sense:add_trigger('->')
@@ -546,10 +548,10 @@ end
 ---
 -- Returns a list of apidocs for the given symbol.
 -- If there are multiple apidocs, the index of one to display is the value of
--- the 'pos' key in the returned list.
--- @param sense The adeptsense returned by adeptsense.new().
+-- the `pos` key in the returned list.
+-- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @param symbol The symbol to get apidocs for.
--- @return apidoc_list or nil
+-- @return apidoc_list or `nil`
 function get_apidoc(sense, symbol)
   if not symbol then return nil end
   local apidocs = { pos = 1 }
@@ -582,8 +584,8 @@ end
 
 ---
 -- Shows a calltip with API documentation for the symbol behind the caret.
--- @param sense The adeptsense returned by adeptsense.new().
--- @return true on success or false.
+-- @param sense The Adeptsense returned by `adeptsense.new()`.
+-- @return `true` on success or `false`.
 -- @see get_symbol
 -- @see get_apidoc
 function show_apidoc(sense)
@@ -628,13 +630,13 @@ end
 
 ---
 -- Loads the given ctags file for autocompletion.
--- It is recommended to pass '-n' to ctags in order to use line numbers instead
+-- It is recommended to pass `-n` to ctags in order to use line numbers instead
 -- of text patterns to locate tags. This will greatly reduce memory usage for a
--- large number of symbols if nolocations is not true.
--- @param sense The adeptsense returned by adeptsense.new().
+-- large number of symbols if `nolocations` is not `true`.
+-- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @param tag_file The path of the ctags file to load.
--- @param nolocations If true, does not store the locations of the tags for use
---   by goto_ctag(). Defaults to false.
+-- @param nolocations If `true`, does not store the locations of the tags for
+--   use by `goto_ctag()`. Defaults to `false`.
 function load_ctags(sense, tag_file, nolocations)
   local ctags_kinds = sense.ctags_kinds
   local completions = sense.completions
@@ -708,8 +710,8 @@ end
 ---
 -- Displays a filteredlist of all known symbols of the given kind (classes,
 -- functions, fields, etc.) and jumps to the source of the selected one.
--- @param sense The adeptsense returned by adeptsense.new().
--- @param k The ctag character kind (e.g. 'f' for a Lua function).
+-- @param sense The Adeptsense returned by `adeptsense.new()`.
+-- @param k The ctag character kind (e.g. `'f'` for a Lua function).
 -- @param title The title for the filteredlist dialog.
 function goto_ctag(sense, k, title)
   if not sense.locations[k] then return end -- no ctags loaded
@@ -744,21 +746,21 @@ function goto_ctag(sense, k, title)
 end
 
 ---
--- Called by load_ctags when a ctag kind is not recognized.
+-- Called by `load_ctags()` when a ctag kind is not recognized.
 -- This method should be replaced with your own that is specific to the
 -- language.
--- @param sense The adeptsense returned by adeptsense.new().
+-- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @param tag_name The tag name.
 -- @param file_name The name of the file the tag belongs to.
--- @param ex_cmd The ex_cmd returned by ctags.
--- @param ext_fields The ext_fields returned by ctags.
+-- @param ex_cmd The `ex_cmd` returned by ctags.
+-- @param ext_fields The `ext_fields` returned by ctags.
 function handle_ctag(sense, tag_name, file_name, ex_cmd, ext_fields) end
 
 ---
--- Clears an adeptsense.
+-- Clears an Adeptsense.
 -- This is necessary for loading a new ctags file or completions from a
 -- different project.
--- @param sense The adeptsense returned by adeptsense.new().
+-- @param sense The Adeptsense returned by `adeptsense.new()`.
 function clear(sense)
   sense.inherited_classes = {}
   sense.completions = {}
@@ -768,17 +770,17 @@ function clear(sense)
 end
 
 ---
--- Called when clearing an adeptsense.
+-- Called when clearing an Adeptsense.
 -- This function should be replaced with your own if you have any persistant
 -- objects that need to be deleted.
--- @param sense The adeptsense returned by adeptsense.new().
+-- @param sense The Adeptsense returned by `adeptsense.new()`.
 function handle_clear(sense) end
 
 ---
--- Creates a new adeptsense for the given lexer language.
+-- Creates a new Adeptsense for the given lexer language.
 -- Only one sense can exist per language.
--- @param lang The lexer language to create an adeptsense for.
--- @return adeptsense.
+-- @param lang The lexer language to create an Adeptsense for.
+-- @return adeptsense
 -- @usage local lua_sense = _m.textadept.adeptsense.new('lua')
 function new(lang)
   local sense = senses[lang]
@@ -798,11 +800,11 @@ function new(lang)
     always_show_globals = true,
 
 ---
--- Contains a map of ctags kinds to adeptsense kinds.
--- Recognized kinds are 'functions', 'fields', and 'classes'. Classes are quite
--- simply containers for functions and fields so Lua modules would count as
--- classes. Any other kinds will be passed to handle_ctag() for user-defined
--- handling.
+-- Contains a map of ctags kinds to Adeptsense kinds.
+-- Recognized kinds are `'functions'`, `'fields'`, and `'classes'`. Classes are
+-- quite simply containers for functions and fields so Lua modules would count
+-- as classes. Any other kinds will be passed to `handle_ctag()` for
+-- user-defined handling.
 -- @usage luasense.ctags_kinds = { 'f' = 'functions' }
 -- @usage csense.ctags_kinds = { 'm' = 'fields', 'f' = 'functions',
 --   c = 'classes', s = 'classes' }
@@ -823,7 +825,7 @@ inherited_classes = {},
 -- Contains lists of possible completions for known symbols.
 -- Each symbol key has a table value that contains a list of field completions
 -- with a `fields` key and a list of functions completions with a `functions`
--- key. This table is normally populated by load_ctags(), but can also be set
+-- key. This table is normally populated by `load_ctags()`, but can also be set
 -- by the user.
 -- @class table
 -- @name completions
@@ -831,27 +833,27 @@ completions = {},
 
 ---
 -- Contains the locations of known symbols.
--- This table is populated by load_ctags().
+-- This table is populated by `load_ctags()`.
 -- @class table
 -- @name locations
 locations = {},
 
 ---
--- Contains a list of api files used by show_apidoc().
+-- Contains a list of api files used by `show_apidoc()`.
 -- Each line in the api file contains a symbol name (not the full symbol)
 -- followed by a space character and then the symbol's documentation. Since
 -- there may be many duplicate symbol names, it is recommended to put the full
--- symbol and arguments, if any, on the first line. (e.g. Class.function(arg1,
--- arg2, ...)). This allows the correct documentation to be shown based on the
--- current context. In the documentation, newlines are represented with '\n'. A
--- '\' before '\n' escapes the newline.
+-- symbol and arguments, if any, on the first line. (e.g. `Class.function(arg1,
+-- arg2, ...)`). This allows the correct documentation to be shown based on the
+-- current context. In the documentation, newlines are represented with `\n`. A
+-- `\` before `\n` escapes the newline.
 -- @class table
 -- @name api_files
 api_files = {},
 
 ---
 -- Contains syntax-specific values for the language.
--- @field self The language's syntax-equivalent of 'self'. Default is 'self'.
+-- @field self The language's syntax-equivalent of `self`. Default is `'self'`.
 -- @field class_definition A Lua pattern representing the language's class
 --   definition syntax. The first capture returned must be the class name. A
 --   second, optional capture contains the class' superclass (if any). If no
@@ -859,19 +861,19 @@ api_files = {},
 --   are shown (if any). Completions will not be shown for both a class and
 --   superclass unless defined in a previously loaded ctags file. Also, multiple
 --   superclasses cannot be recognized by this pattern; use a ctags file
---   instead. Defaults to 'class%s+([%w_]+)'.
--- @field word_chars A Lua pattern of characters allowed in a word. Default is
---   '%w_'.
+--   instead. Defaults to `'class%s+([%w_]+)'`.
+-- @field word_chars A Lua pattern of characters allowed in a word. The default
+--   is `'%w_'`.
 -- @field symbol_chars A Lua pattern of characters allowed in a symbol,
---   including member operators. The pattern should be a character set. Default
---   is '[%w_%.]'.
+--   including member operators. The pattern should be a character set. The
+--   default is `'[%w_%.]'`.
 -- @field type_declarations A list of Lua patterns used for determining the
 --   class type of a symbol. The first capture returned must be the class name.
---   Use '%_' to match the symbol. Defaults to '(%u[%w_%.]+)%s+%_'.
+--   Use `%_` to match the symbol. The default is `'(%u[%w_%.]+)%s+%_'`.
 -- @field type_declarations_exclude A table of types to exclude, even if they
 --   match a type_declaration pattern. Each excluded type is a table key and has
---   a true boolean value. For example, { Foo = true } excludes any type whose
---   name is 'Foo'. Defaults to being empty.
+--   a `true` boolean value. For example, `{ Foo = true }` excludes any type
+--   whose name is `Foo`. Defaults to being empty.
 -- @field type_assignments A map of Lua patterns to class types for variable
 --   assignments. This is typically used for dynamically typed languages. For
 --   example, `sense.type_assignments['^"'] = 'string'`  would recognize string
@@ -902,7 +904,7 @@ end
 ---
 -- Completes the symbol at the current position based on the current lexer's
 -- Adeptsense.
--- This should be called by key commands and menus instead of `complete`.
+-- This should be called by key commands and menus instead of `complete()`.
 function complete_symbol()
   local m = _m[buffer:get_lexer()]
   if m and m.sense then m.sense:complete() end
@@ -911,7 +913,7 @@ end
 ---
 -- Shows API documentation for the symbol at the current position based on the
 -- current lexer's Adeptsense.
--- This should be called by key commands and menus instead of `show_apidoc`.
+-- This should be called by key commands and menus instead of `show_apidoc()`.
 function show_documentation()
   local m = _m[buffer:get_lexer()]
   if m and m.sense then m.sense:show_apidoc() end
diff --git a/modules/textadept/bookmarks.lua b/modules/textadept/bookmarks.lua
index a032d19c..0b90c28a 100644
--- a/modules/textadept/bookmarks.lua
+++ b/modules/textadept/bookmarks.lua
@@ -10,7 +10,7 @@ module('_m.textadept.bookmarks', package.seeall)
 -- ## Settings
 --
 -- * `MARK_BOOKMARK_COLOR` [number]: The color used for a bookmarked line in
---   0xBBGGRR format.
+--   `0xBBGGRR` format.
 
 -- settings
 MARK_BOOKMARK_COLOR = 0xC08040
diff --git a/modules/textadept/editing.lua b/modules/textadept/editing.lua
index cb340cfc..06427795 100644
--- a/modules/textadept/editing.lua
+++ b/modules/textadept/editing.lua
@@ -13,19 +13,19 @@ module('_m.textadept.editing', package.seeall)
 --
 -- * `AUTOPAIR` [bool]: Opening `(`, `[`, `[`, `"`, or `'` characters are
 --   automatically closed. The default value is `true`.
--- * `HIGHLIGHT_BRACES` [bool]: Highlight matching '()[]{}<>' characters. The
+-- * `HIGHLIGHT_BRACES` [bool]: Highlight matching `()[]{}<>` characters. The
 --   default value is `true`.
 -- * `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]: Strip trailing whitespace on file save.
 --   The default value is `true`.
 -- * `MARK_HIGHLIGHT_BACK` [number]: The background color used for a line
---   containing a highlighted word in 0xBBGGRR format.
+--   containing a highlighted word in `0xBBGGRR` format.
 -- * `INDIC_HIGHLIGHT_BACK` [number]: The color used for an indicator for a
---   highlighted word in 0xBBGGRR format.
--- * `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.
+--   highlighted word in `0xBBGGRR` format.
+-- * `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`.
 
 -- settings
 AUTOPAIR = true
@@ -39,7 +39,7 @@ INDIC_HIGHLIGHT_ALPHA = 100
 
 ---
 -- Comment strings for various lexer languages.
--- Used for the block_comment() function. Keys are lexer language names and
+-- Used for 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
@@ -156,8 +156,8 @@ events.connect(events.AUTO_C_SELECTION, function(text, position)
 end)
 
 ---
--- Goes to a matching brace position, selecting the text inside if specified.
--- @param select If true, selects the text between matching braces.
+-- Goes to a matching brace position, selecting the text inside if specified to.
+-- @param select If `true`, selects the text between matching braces.
 function match_brace(select)
   local buffer = buffer
   local caret = buffer.current_pos
@@ -179,7 +179,7 @@ end
 -- Pops up an autocompletion list for the current word based on other words in
 -- the document.
 -- @param word_chars String of chars considered to be part of words.
--- @return true if there were completions to show; false otherwise.
+-- @return `true` if there were completions to show; `false` otherwise.
 function autocomplete_word(word_chars)
   local buffer = buffer
   local caret, length = buffer.current_pos, buffer.length
@@ -254,7 +254,8 @@ end
 
 ---
 -- Goes to the requested line.
--- @param line Optional line number to go to.
+-- @param line Optional line number to go to. If `nil`, the user is prompted for
+--   one.
 function goto_line(line)
   if not line then
     line = tonumber(gui.dialog('standard-inputbox',
@@ -305,7 +306,7 @@ events.connect(events.FILE_BEFORE_SAVE, prepare_for_save)
 
 ---
 -- Selects the current word under the caret and if action indicates, deletes it.
--- @param action Optional action to perform with selected word. If 'delete', it
+-- @param action Optional action to perform with selected word. If `delete`, it
 --   is deleted.
 function current_word(action)
   local buffer = buffer
diff --git a/modules/textadept/find.lua b/modules/textadept/find.lua
index 8debc7ec..8187954e 100644
--- a/modules/textadept/find.lua
+++ b/modules/textadept/find.lua
@@ -88,12 +88,12 @@ end
 -- @param next Flag indicating whether or not the search direction is forward.
 -- @param flags Search flags. This is a number mask of 4 flags: match case (2),
 --   whole word (4), Lua pattern (8), and in files (16) joined with binary OR.
---   If nil, this is determined based on the checkboxes in the find box.
--- @param nowrap Flag indicating whether or not the search won't wrap.
+--   If `nil`, this is determined based on the checkboxes in the find box.
+-- @param nowrap Flag indicating whether or not the search will not wrap.
 -- @param wrapped Utility flag indicating whether or not the search has wrapped
 --   for displaying useful statusbar information. This flag is used and set
 --   internally, and should not be set otherwise.
--- @return position of the found text or -1
+-- @return position of the found text or `-1`
 local function find_(text, next, flags, nowrap, wrapped)
   if text == '' then return end
   local buffer = buffer
@@ -161,7 +161,7 @@ events.connect(events.FIND, find_)
 
 -- Finds and selects text incrementally in the current buffer from a start
 -- point.
--- Flags other than SCFIND_MATCHCASE are ignored.
+-- Flags other than `SCFIND_MATCHCASE` are ignored.
 -- @param text The text to find.
 local function find_incremental(text)
   local flags = find.match_case and c.SCFIND_MATCHCASE or 0
@@ -206,7 +206,7 @@ local loadstring = loadstring
 local pcall = pcall
 
 -- Runs the given code.
--- This function is passed to string.gsub() in the replace() function.
+-- This function is passed to `string.gsub()` in the `replace()` function.
 -- @param code The code to run.
 local function run(code)
   local ok, val = pcall(loadstring('return '..code))
@@ -222,11 +222,11 @@ local function run(code)
 end
 
 -- Replaces found text.
--- 'find_' is called first, to select any found text. The selected text is then
--- replaced by the specified replacement text.
+-- `find_()` is called first, to select any found text. The selected text is
+-- then replaced by the specified replacement text.
 -- This function ignores 'Find in Files'.
 -- @param rtext The text to replace found text with. It can contain both Lua
---   capture items (%n where 1 <= n <= 9) for Lua pattern searches and %()
+--   capture items (`%n` where 1 <= `n` <= 9) for Lua pattern searches and `%()`
 --   sequences for embedding Lua code for any search.
 -- @see find
 local function replace(rtext)
@@ -259,7 +259,7 @@ events.connect(events.REPLACE, replace)
 -- This function ignores 'Find in Files'.
 -- @param ftext The text to find.
 -- @param rtext The text to replace found text with.
--- @param flags The number mask identical to the one in 'find'.
+-- @param flags The number mask identical to the one in `find_()`.
 -- @see find
 local function replace_all(ftext, rtext, flags)
   if #ftext == 0 then return end
diff --git a/modules/textadept/menu.lua b/modules/textadept/menu.lua
index d022d47e..6832bb1f 100644
--- a/modules/textadept/menu.lua
+++ b/modules/textadept/menu.lua
@@ -6,7 +6,7 @@ local gui = gui
 
 ---
 -- Provides dynamic menus for Textadept.
--- This module should be 'require'ed last, after _m.textadept.keys since it
+-- This module should be `require`ed last, after `_m.textadept.keys` since it
 -- looks up defined key commands to show them in menus.
 module('_m.textadept.menu', package.seeall)
 
@@ -216,7 +216,7 @@ menubar = {
 }
 
 ---
--- Contains the right-click context menu.
+-- Contains the default right-click context menu.
 -- @class table
 -- @name context_menu
 context_menu = {
@@ -235,12 +235,13 @@ local key_shortcuts = {}
 local menu_actions = {}
 local contextmenu_actions = {}
 
--- Creates a menu suitable for gui.gtkmenu from the menu table format.
+-- Creates a menu suitable for `gui.gtkmenu()` from the menu table format.
 -- Also assigns key commands.
 -- @param menu The menu to create a gtkmenu from.
 -- @param contextmenu Flag indicating whether or not the menu is a context menu.
---   If so, menu_id offset is 1000. Defaults to false.
--- @return gtkmenu that can be passed to gui.gtkmenu.
+--   If so, menu_id offset is 1000. Defaults to `false`.
+-- @return gtkmenu that can be passed to `gui.gtkmenu()`.
+-- @see gui.gtkmenu
 local function read_menu_table(menu, contextmenu)
   local gtkmenu = {}
   gtkmenu.title = menu.title
@@ -263,14 +264,14 @@ local function read_menu_table(menu, contextmenu)
 end
 
 ---
--- Sets gui.menubar from the given table of menus.
+-- Sets `gui.menubar` from the given table of menus.
 -- @param menubar The table of menus to create the menubar from. Each table
 --   entry is another table that corresponds to a particular menu. A menu can
---   have a 'title' key with string value. Each menu item is either a submenu
+--   have a `title` key with string value. Each menu item is either a submenu
 --   (another menu table) or a table consisting of two items: string menu text
 --   and a function or action table just like in `keys`. The table can
 --   optionally contain 2 more number values: a GDK keycode and modifier mask
---   for setting a menu accelerator. If the menu text is 'separator', a menu
+--   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
 function set_menubar(menubar)
@@ -286,7 +287,7 @@ end
 set_menubar(menubar)
 
 ---
--- Sets gui.context_menu from the given menu table.
+-- Sets `gui.context_menu` from the given menu table.
 -- @param menu_table The menu table to create the context menu from. Each table
 --   entry is either a submenu or menu text and a function or action table.
 -- @see set_menubar
@@ -326,8 +327,8 @@ function select_command()
 end
 
 ---
--- Rebuilds the tables used by select_command().
--- This should be called every time set_menubar() is called.
+-- Rebuilds the tables used by `select_command()`.
+-- This should be called every time `set_menubar()` is called.
 function rebuild_command_tables()
   items, commands = {}, {}
   build_command_tables(menubar, nil, items, commands)
diff --git a/modules/textadept/mime_types.lua b/modules/textadept/mime_types.lua
index 119d5b55..51b60636 100644
--- a/modules/textadept/mime_types.lua
+++ b/modules/textadept/mime_types.lua
@@ -14,7 +14,7 @@ module('_m.textadept.mime_types', package.seeall)
 --
 -- * **buffer:set\_lexer** (language)<br />
 --   Replacement for [`buffer:set_lexer_language()`][buffer_set_lexer_language].
---   <br /> Sets a buffer._lexer field so it can be restored without querying
+--   <br /> Sets a `buffer._lexer` field so it can be restored without querying
 --   the mime-types tables. Also if the user manually sets the lexer, it should
 --   be restored.<br />
 --   Loads the language-specific module if it exists.
@@ -50,7 +50,7 @@ shebangs = {}
 -- @name patterns
 patterns = {}
 
--- Load mime-types from mime_types.conf
+-- Load mime-types from `modules/textadept/mime_types.conf`.
 local mime_types
 local f = io.open(_HOME..'/modules/textadept/mime_types.conf', 'rb')
 if f then
@@ -100,6 +100,14 @@ end
 for lexer in pairs(lexers_found) do lexers[#lexers + 1] = lexer end
 table.sort(lexers)
 
+---
+-- Prompts the user to select a lexer from a filtered list for the current
+-- buffer.
+function select_lexer()
+  local lexer = gui.filteredlist(L('Select Lexer'), 'Name', lexers)
+  if lexer then buffer:set_lexer(lexer) end
+end
+
 -- LuaDoc is in core/.buffer.luadoc.
 local function get_style_name(buffer, style_num)
   buffer:check_global()
@@ -109,7 +117,7 @@ end
 
 -- Contains the whitespace styles for lexers.
 -- These whitespace styles are used to determine the lexer at the current caret
--- position since the styles have the name '[lang]_whitespace'.
+-- position since the styles have the name `[lang]_whitespace`.
 -- @class table
 -- @name ws_styles
 local ws_styles = {}
@@ -130,9 +138,8 @@ local function set_lexer(buffer, lang)
   local module_not_found = "^module '"..lang.."[^\']*' not found:"
   if not ok and not err:find(module_not_found) then error(err) end
   buffer:colourise(0, -1)
+  -- Create the ws_styles[lexer] lookup table for `get_lexer()`.
   if ws_styles[lang] then return end
-
-  -- Create the ws_styles[lexer] lookup table for get_lexer().
   local ws = {}
   for i = 0, 255 do
     ws[i] = buffer:private_lexer_call(i):find('whitespace') ~= nil
@@ -196,11 +203,3 @@ events.connect(events.VIEW_NEW, restore_lexer, 1)
 
 events.connect(events.RESET_AFTER,
                function() buffer:set_lexer(buffer._lexer or 'container') end)
-
----
--- Prompts the user to select a lexer from a filtered list for the current
--- buffer.
-function select_lexer()
-  local lexer = gui.filteredlist(L('Select Lexer'), 'Name', lexers)
-  if lexer then buffer:set_lexer(lexer) end
-end
diff --git a/modules/textadept/run.lua b/modules/textadept/run.lua
index 567178fb..39a71db1 100644
--- a/modules/textadept/run.lua
+++ b/modules/textadept/run.lua
@@ -15,14 +15,14 @@ module('_m.textadept.run', package.seeall)
 --
 -- * `_G.events.COMPILE_OUTPUT`: Called after a compile command is executed.
 --   When connecting to this event (typically from a language-specific module),
---   connect with an index of 1 and return `true` if the event was handled and
+--   connect with an index of `1` and return `true` if the event was handled and
 --   you want to override the default handler that prints the output to a new
 --   view.<br />
 --       * `lexer`: The lexer language.
 --       * `output`: The output from the command.
 -- * `_G.events.RUN_OUTPUT`: Called after a run command is executed. When
 --   connecting to this event (typically from a language-specific module),
---   connect with an index of 1 and return `true` if the event was handled and
+--   connect with an index of `1` and return `true` if the event was handled and
 --   you want to override the default handler that prints the output to a new
 --   view.<br />
 --       * `lexer`: The lexer language.
@@ -36,10 +36,10 @@ events.RUN_OUTPUT = 'run_output'
 -- Executes the command line parameter and prints the output to Textadept.
 -- @param command The command line string.
 --   It can have the following macros:
---     * %(filepath) The full path of the current file.
---     * %(filedir) The current file's directory path.
---     * %(filename) The name of the file including extension.
---     * %(filename_noext) The name of the file excluding extension.
+--     + `%(filepath)`: The full path of the current file.
+--     + `%(filedir)`: The current file's directory path.
+--     + `%(filename)`: The name of the file including extension.
+--     + `%(filename_noext)`: The name of the file excluding extension.
 function execute(command)
   local filepath = buffer.filename:iconv(_CHARSET, 'UTF-8')
   local filedir, filename = '', filepath
@@ -63,7 +63,7 @@ function execute(command)
 end
 
 -- Executes a compile or run command.
--- @param cmd_table Either compile_command or run_command
+-- @param cmd_table Either `compile_command` or `run_command`.
 local function command(cmd_table)
   if not buffer.filename then return end
   buffer:save()
@@ -82,7 +82,7 @@ end
 compile_command = {}
 
 ---
--- Compiles the file as specified by its extension in the compile_command
+-- Compiles the file as specified by its extension in the `compile_command`
 -- table.
 -- @see compile_command
 function compile()
@@ -102,7 +102,7 @@ events.connect(events.COMPILE_OUTPUT,
 run_command = {}
 
 ---
--- Runs/executes the file as specified by its extension in the run_command
+-- Runs/executes the file as specified by its extension in the `run_command`
 -- table.
 -- @see run_command
 function run()
@@ -114,15 +114,15 @@ events.connect(events.RUN_OUTPUT,
 ---
 -- A table of error string details.
 -- Each entry is a table with the following fields:
---   pattern: the Lua pattern that matches a specific error string.
---   filename: the index of the Lua capture that contains the filename the error
---     occured in.
---   line: the index of the Lua capture that contains the line number the error
---     occured on.
---   message: [Optional] the index of the Lua capture that contains the error's
---     message. A call tip will be displayed if a message was captured.
+--   + `pattern`: The Lua pattern that matches a specific error string.
+--   + `filename`: The index of the Lua capture that contains the filename the
+--     error occured in.
+--   + `line`: The index of the Lua capture that contains the line number the
+--     error occured on.
+--   + `message`: [Optional] The index of the Lua capture that contains the
+--     error's message. A call tip will be displayed if a message was captured.
 -- When an error message is double-clicked, the user is taken to the point of
---   error.
+-- error.
 -- This table is usually populated by language-specific modules.
 -- @class table
 -- @name error_detail
diff --git a/modules/textadept/session.lua b/modules/textadept/session.lua
index 9890b7f2..00d73b56 100644
--- a/modules/textadept/session.lua
+++ b/modules/textadept/session.lua
@@ -11,10 +11,10 @@ module('_m.textadept.session', package.seeall)
 --
 -- * `DEFAULT_SESSION` [string]: The path to the default session file.
 -- * `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.
+--   `true` and can be disabled by passing the command line switch `-n` or
+--   `--nosession` to Textadept.
 -- * `MAX_RECENT_FILES` [number]: The maximum number of files from the recent
---   files list to save to the session. The default is 10.
+--   files list to save to the session. The default is `10`.
 
 -- settings
 DEFAULT_SESSION = _USERHOME..'/session'
@@ -27,8 +27,8 @@ MAX_RECENT_FILES = 10
 -- Textadept restores split views, opened buffers, cursor information, and
 -- project manager details.
 -- @param filename The absolute path to the session file to load. Defaults to
---   DEFAULT_SESSION if not specified.
--- @return true if the session file was opened and read; false otherwise.
+--   `DEFAULT_SESSION` if not specified.
+-- @return `true` if the session file was opened and read; `false` otherwise.
 -- @usage _m.textadept.session.load(filename)
 function load(filename)
   local not_found = {}
@@ -104,7 +104,7 @@ events.connect('arg_none', function() if SAVE_ON_QUIT then load() end end)
 -- Saves split views, opened buffers, cursor information, and project manager
 -- details.
 -- @param filename The absolute path to the session file to save. Defaults to
---   either the current session file or DEFAULT_SESSION if not specified.
+--   either the current session file or `DEFAULT_SESSION` if not specified.
 -- @usage _m.textadept.session.save(filename)
 function save(filename)
   local session = {}
@@ -196,4 +196,3 @@ events.connect(events.QUIT, function() if SAVE_ON_QUIT then save() end end, 1)
 
 local function no_session() SAVE_ON_QUIT = false end
 args.register('-n', '--nosession', 0, no_session, 'No session functionality')
-
diff --git a/modules/textadept/snapopen.lua b/modules/textadept/snapopen.lua
index 17979a2d..f06d9260 100644
--- a/modules/textadept/snapopen.lua
+++ b/modules/textadept/snapopen.lua
@@ -11,8 +11,9 @@ module('_m.textadept.snapopen', package.seeall)
 --
 -- * `PATHS` [table]: Table of default UTF-8 paths to search.
 -- * `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.
+--   value is `4`.
+-- * `MAX` [number]: Maximum number of files to list. The default value is
+--   `1000`.
 --
 -- ## Examples
 --
@@ -43,7 +44,7 @@ local DEPTH = DEFAULT_DEPTH
 -- Determines whether or not the given file matches the given filter.
 -- @param file The filename.
 -- @param filter The filter table.
--- @return boolean true or false.
+-- @return boolean `true` or `false`.
 local function exclude(file, filter)
   if not filter then return false end
   local string_match, string_sub = string.match, string.sub
@@ -88,14 +89,14 @@ end
 --   paths to search.
 -- @param filter A filter for files and folders to exclude. The filter may be
 --   a string or table. Each filter is a Lua pattern. Any files matching a
---   filter are excluded. Prefix a pattern with '!' to exclude any files that
+--   filter are excluded. Prefix a pattern with `!` to exclude any files that
 --   do not match the filter. Directories can be excluded by adding filters to
---   a table assigned to a 'folders' key in the filter table. All strings should
+--   a table assigned to a `folders` key in the filter table. All strings should
 --   be UTF-8 encoded.
--- @param exclusive Flag indicating whether or not to exclude PATHS in the
---   search. Defaults to false.
+-- @param exclusive Flag indicating whether or not to exclude `PATHS` in the
+--   search. Defaults to `false`.
 -- @param depth Number of directories to recurse into for finding files.
---   Defaults to DEFAULT_DEPTH.
+--   Defaults to `DEFAULT_DEPTH`.
 -- @usage _m.textadept.snapopen.open()
 -- @usage _m.textadept.snapopen.open(buffer.filename:match('^.+/'), nil, true)
 -- @usage _m.textadept.snapopen.open(nil, '!%.lua$')
diff --git a/modules/textadept/snippets.lua b/modules/textadept/snippets.lua
index 337e056e..23638862 100644
--- a/modules/textadept/snippets.lua
+++ b/modules/textadept/snippets.lua
@@ -120,8 +120,8 @@ module('_m.textadept.snippets', package.seeall)
 -- The stack of currently running snippets.
 local snippet_stack = {}
 
--- Contains newline sequences for buffer.eol_mode.
--- This table is used by new_snippet().
+-- Contains newline sequences for `buffer.eol_mode`.
+-- This table is used by `new_snippet()`.
 -- @class table
 -- @name newlines
 local newlines = { [0] = '\r\n', '\r', '\n' }
@@ -174,7 +174,7 @@ end
 -- Inserts a snippet.
 -- @param text Optional snippet text. If none is specified, the snippet text
 --   is determined from the trigger and lexer.
--- @return false if no snippet was expanded; true otherwise.
+-- @return `false` if no snippet was expanded; `true` otherwise.
 function _insert(text)
   local buffer = buffer
   local trigger
@@ -196,7 +196,7 @@ end
 ---
 -- Goes back to the previous placeholder, reverting any changes from the current
 -- one.
--- @return false if no snippet is active; nil otherwise.
+-- @return `false` if no snippet is active; `nil` otherwise.
 function _previous()
   if #snippet_stack == 0 then return false end
   snippet_stack[#snippet_stack]:previous()
@@ -253,8 +253,8 @@ local escapes = {
 -- @class table
 -- @name _snippet_mt
 _snippet_mt = {
-  -- Gets a snippet's end position in the Scintilla buffer.
-  -- @param snippet The snippet returned by new_snippet().
+  -- Gets a snippet's end position in the buffer.
+  -- @param snippet The snippet returned by `new_snippet()`.
   get_end_position = function(snippet)
     local e = buffer:indicator_end(INDIC_SNIPPET, snippet.start_position + 1)
     if e == 0 then e = snippet.start_position end
@@ -262,7 +262,7 @@ _snippet_mt = {
   end,
 
   -- Gets the text for a snippet.
-  -- @param snippet The snippet returned by new_snippet().
+  -- @param snippet The snippet returned by `new_snippet()`.
   get_text = function(snippet)
     local s, e = snippet.start_position, snippet:get_end_position()
     local ok, text = pcall(buffer.text_range, buffer, s, e)
@@ -270,8 +270,8 @@ _snippet_mt = {
   end,
 
   -- Sets the text for a snippet.
-  -- This text will be displayed immediately in the Scintilla buffer.
-  -- @param snippet The snippet returned by new_snippet().
+  -- This text will be displayed immediately in the buffer.
+  -- @param snippet The snippet returned by `new_snippet()`.
   -- @param text The snippet's text.
   set_text = function(snippet, text)
     local buffer = buffer
@@ -281,25 +281,25 @@ _snippet_mt = {
   end,
 
   -- Returns the escaped form of the snippet's text.
-  -- @param snippet The snippet returned by new_snippet().
+  -- @param snippet The snippet returned by `new_snippet()`.
   -- @see escapes
   get_escaped_text = function(snippet)
     return snippet:get_text():gsub('%%[%%%(%)>%]]', escapes)
   end,
 
   -- Returns the unescaped form of the given text.
-  -- This does the opposite of get_escaped_text() by default. The behaviour is
-  -- slightly different when the 'complete' parameter is true.
+  -- This does the opposite of `get_escaped_text()` by default. The behaviour is
+  -- slightly different when `complete` true.
   -- @param text Text to unescape.
   -- @param complete Flag indicating whether or not to also remove the extra
-  --   escape character '%'. Defaults to false.
+  --   escape character '%'. Defaults to `false`.
   unescape_text = function(text, complete)
     text = text:gsub('\027.', escapes)
     return complete and text:gsub('%%([%%%(%)>%]])', '%1') or text
   end,
 
   -- Executes code in the snippet for the given index.
-  -- @param snippet The snippet returned by new_snippet().
+  -- @param snippet The snippet returned by `new_snippet()`.
   -- @param index Execute code with this index.
   execute_code = function(snippet, index)
     local escaped_text = snippet:get_escaped_text()
@@ -322,7 +322,7 @@ _snippet_mt = {
   end,
 
   -- Goes to the next placeholder in a snippet.
-  -- @param snippet The snippet returned by new_snippet().
+  -- @param snippet The snippet returned by `new_snippet()`.
   next = function(snippet)
     local buffer = buffer
     -- If the snippet was just initialized, determine how many placeholders it
@@ -374,7 +374,7 @@ _snippet_mt = {
   end,
 
   -- Goes to the previous placeholder in a snippet.
-  -- @param snippet The snippet returned by new_snippet().
+  -- @param snippet The snippet returned by `new_snippet()`.
   previous = function(snippet)
     if snippet.index > 2 then
       snippet:set_text(snippet.snapshots[snippet.index - 2])
@@ -386,7 +386,7 @@ _snippet_mt = {
   end,
 
   -- Cancels a snippet.
-  -- @param snippet The snippet returned by new_snippet().
+  -- @param snippet The snippet returned by `new_snippet()`.
   cancel = function(snippet)
     local buffer = buffer
     buffer:set_sel(snippet.start_position, snippet:get_end_position())
@@ -396,8 +396,8 @@ _snippet_mt = {
     snippet_stack[#snippet_stack] = nil
   end,
 
-  -- Finishes a snippet by going to its '%0' placeholder and cleaning up.
-  -- @param snippet The snippet returned by new_snippet().
+  -- Finishes a snippet by going to its `%0` placeholder and cleaning up.
+  -- @param snippet The snippet returned by `new_snippet()`.
   finish = function(snippet)
     local buffer = buffer
     snippet:set_text(snippet.unescape_text(snippet:get_text(), true))
@@ -423,7 +423,7 @@ events.connect(events.VIEW_NEW,
                function() buffer.indic_style[INDIC_SNIPPET] = INDIC_HIDDEN end)
 
 ---
--- Provides access to snippets from _G.
+-- Provides access to snippets from `_G`.
 -- @class table
 -- @name _G.snippets
 _G.snippets = _M