More LuaDoc updates.

11 files changed, 78 insertions, 71 deletions

diff --git a/core/.buffer.luadoc b/core/.buffer.luadoc
index 3c6264c4..711ab255 100644
--- a/core/.buffer.luadoc
+++ b/core/.buffer.luadoc
@@ -73,7 +73,8 @@
 --   The default value is `true`.
 -- @field auto_c_cancel_at_start (bool)
 --   Cancel an autocompletion or user list when backspacing to a position before
---   where autocompletion started instead of before the word being completed.
+--   where autocompletion started (instead of before the word being completed)
+--   or where the user list was shown.
 --   The default value is `true`.
 -- @field auto_c_case_insensitive_behaviour (number)
 --   The behavior mode for a case insensitive autocompletion or user list when
@@ -90,9 +91,10 @@
 --   option has no effect for a user list.
 --   The default value is `false`.
 -- @field auto_c_current (number, Read-only)
---   The index of the currently selected item in the autocompletion list.
+--   The index of the currently selected item in the autocompletion or user
+--   list.
 -- @field auto_c_current_text (string, Read-only)
---   The text of the currently selected item in the autocompletion list.
+--   The text of the currently selected item in the autocompletion or user list.
 -- @field auto_c_drop_rest_of_word (bool)
 --   Delete word characters after autocompleted text.
 --   The default value is `false`.
@@ -113,7 +115,7 @@
 --   The default value is `0`, which automatically sizes the width to fit the
 --   longest item.
 -- @field auto_c_order (number)
---   The order setting for autocompletion lists.
+--   The order setting for autocompletion and user lists.
 --
 --   * `buffer.ORDER_PRESORTED`
 --     Lists passed to [`buffer.auto_c_show`](#auto_c_show) are in sorted,
@@ -126,14 +128,16 @@
 --
 --   The default value is `buffer.ORDER_PRESORTED`.
 -- @field auto_c_separator (number)
---   The byte value of the character that separates autocompletion list items.
+--   The byte value of the character that separates autocompletion and user list
+--   items.
 --   The default value is `32` (' ').
 -- @field auto_c_type_separator (number)
---   The character byte that separates autocompletion and list items and their
---   image types.
---   Autocompletion list items can display both an image and text. Register
---   images and their types using [`buffer:register_image()`](#register_image)
---   or [`buffer:register_rgba_image()`](#register_rgba_image) before appending
+--   The character byte that separates autocompletion and user list items and
+--   their image types.
+--   Autocompletion and user list items can display both an image and text.
+--   Register images and their types using
+--   [`buffer:register_image()`](#register_image) or
+--   [`buffer:register_rgba_image()`](#register_rgba_image) before appending
 --   image types to list items after type separator characters.
 --   The default value is 63 ('?').
 -- @field back_space_un_indents (bool)
@@ -425,8 +429,7 @@
 --   Table of positions at the ends of indentation for line numbers starting
 --   from zero.
 -- @field line_indentation (table)
---   Table of indentation amounts in character columns, for line numbers
---   starting from zero.
+--   Table of column indentation amounts, for line numbers starting from zero.
 -- @field line_state (table)
 --   Table of integer line states for line numbers starting from zero.
 --   Line states are used for storing longer lived parse states per line. They
@@ -604,7 +607,7 @@
 --   [`buffer:marker_define_rgba_image()`](#marker_define_rgba_image) and
 --   [`buffer:register_rgba_image()`](#register_rgba_image).
 -- @field scroll_width (number)
---   The assumed buffer width for horizontal scrolling purposes.
+--   The horizontal scroll pixel width.
 --   For performance, the view does not measure the display width of the buffer
 --   to determine the properties of the horizontal scroll bar, but uses an
 --   assumed width instead. To ensure the width of the currently visible lines
@@ -620,13 +623,14 @@
 --   [`buffer:search_in_target()`](#search_in_target).
 --
 --   * `buffer.FIND_WHOLEWORD`
---     Match text surrounded by non-word characters.
+--     Match the search text surrounded by non-word characters.
 --   * `buffer.FIND_MATCHCASE`
---     Match text case sensitively.
+--     Match the search text case sensitively.
 --   * `buffer.FIND_WORDSTART`
---     Match text only when the previous character is a non-word character.
+--     Match the search text only when the previous character is a non-word
+--     character.
 --   * `buffer.FIND_REGEXP`
---     Interpret the search string as a regular expression.
+--     Interpret the search text as a regular expression.
 --
 --   The default value is `0`.
 --
@@ -952,13 +956,13 @@ function annotation_clear_all(buffer) end
 function append_text(buffer, text) end
 
 ---
--- Returns whether or not the autocompletion list is visible.
+-- Returns whether or not the autocompletion or user list is visible.
 -- @param buffer The global buffer.
 -- @return bool
 function auto_c_active(buffer) end
 
 ---
--- Cancels the autocompletion list.
+-- Cancels the autocompletion or user list.
 -- @param buffer The global buffer.
 function auto_c_cancel(buffer) end
 
@@ -968,14 +972,16 @@ function auto_c_cancel(buffer) end
 function auto_c_complete(buffer) end
 
 ---
--- Returns the position where autocompletion started at.
+-- Returns the position where autocompletion started or where the user list was
+-- shown.
 -- @param buffer The global buffer.
 -- @return number
 function auto_c_pos_start(buffer) end
 
 ---
--- Selects the first item in the autocompletion list that starts with *string*,
--- considering case sensitiveness based on `buffer.auto_c_ignore_case`.
+-- Selects the first item in the autocompletion or user list that starts with
+-- *string*, considering case sensitiveness based on
+-- `buffer.auto_c_ignore_case`.
 -- @param buffer The global buffer.
 -- @param string The item in the list to select.
 function auto_c_select(buffer, string) end
@@ -2076,7 +2082,7 @@ function redo(buffer) end
 
 ---
 -- Registers XPM image *xpm_data* to type number *type* for use in
--- autocompletion lists.
+-- autocompletion and user lists.
 -- @param buffer The global buffer.
 -- @param type Integer type to register the image with.
 -- @param xpm_data The XPM data as described in `buffer:marker_define_pixmap()`.
@@ -2084,7 +2090,7 @@ function register_image(buffer, type, xpm_data) end
 
 ---
 -- Registers RGBA image *pixels* to type number *type* for use in autocompletion
--- lists.
+-- and user lists.
 -- The dimensions for *pixels*, `buffer.rgba_image_width` and
 -- `buffer.rgba_image_height`, must have already been defined. *pixels* is a
 -- sequence of 4 byte pixel values (red, blue, green, and alpha) defining the
@@ -2473,7 +2479,7 @@ function undo(buffer) end
 function upper_case(buffer) end
 
 ---
--- Displays a list identified by list identifier number *list_item* and
+-- Displays a user list identified by list identifier number *list_item* and
 -- constructed from string *item_list*, whose items are delimited by
 -- `buffer.auto_c_separator` characters.
 -- The sorted order of *item_list*, `buffer.auto_c_order`, must have already
diff --git a/core/file_io.lua b/core/file_io.lua
index 09533196..b68247ad 100644
--- a/core/file_io.lua
+++ b/core/file_io.lua
@@ -346,19 +346,21 @@ end
 -- directory paths, using a filtered list dialog.
 -- Files shown in the dialog do not match any pattern in string or table
 -- *filter*, and, unless *exclude_FILTER* is `true`, `lfs.FILTER` as well. A
--- filter table contains Lua patterns that match filenames to exclude, with
--- patterns matching folders to exclude listed in a `folders` sub-table.
--- Patterns starting with '!' exclude files and folders that do not match the
--- pattern that follows. Use a table of raw file extensions assigned to an
--- `extensions` key for fast filtering by extension. The number of files in the
--- list is capped at `SNAPOPEN_MAX`.
+-- filter table contains Lua patterns that match filenames to exclude, an
+-- optional `folders` sub-table that contains patterns matching folders to
+-- exclude, and an optional `extensions` sub-table that contains raw file
+-- extensions to exclude. Any patterns starting with '!' exclude files and
+-- folders that do not match the pattern that follows. The number of files in
+-- the list is capped at `SNAPOPEN_MAX`.
+-- *opts* is an optional table of additional options for
+-- `ui.dialogs.filteredlist()`.
 -- @param paths String directory path or table of directory paths to search.
 -- @param filter Optional filter for files and folders to exclude.
 -- @param exclude_FILTER Optional flag indicating whether or not to exclude the
 --   default filter `lfs.FILTER` in the search. If `false`, adds `lfs.FILTER` to
 --   *filter*.
 --   The default value is `false` to include the default filter.
--- @param opts Optional additional options to pass to
+-- @param opts Optional table of additional options for
 --   `ui.dialogs.filteredlist()`.
 -- @usage io.snapopen(buffer.filename:match('^.+/')) -- list all files in the
 --   current file's directory, subject to the default filter
@@ -368,6 +370,7 @@ end
 --   files in a project directory
 -- @see lfs.FILTER
 -- @see SNAPOPEN_MAX
+-- @see ui.dialogs.filteredlist
 -- @name snapopen
 function io.snapopen(paths, filter, exclude_FILTER, opts)
   if type(paths) == 'string' then paths = {paths} end
diff --git a/core/lfs_ext.lua b/core/lfs_ext.lua
index 6e4f0ccf..633aee50 100644
--- a/core/lfs_ext.lua
+++ b/core/lfs_ext.lua
@@ -44,11 +44,11 @@ end
 -- function *f* on each file found.
 -- Files *f* is called on do not match any pattern in string or table *filter*,
 -- and, unless *exclude_FILTER* is `true`, `FILTER` as well. A filter table
--- contains Lua patterns that match filenames to exclude, with patterns matching
--- folders to exclude listed in a `folders` sub-table. Patterns starting with
--- '!' exclude files and folders that do not match the pattern that follows. Use
--- a table of raw file extensions assigned to an `extensions` key for fast
--- filtering by extension.
+-- contains Lua patterns that match filenames to exclude, an optional `folders`
+-- sub-table that contains patterns matching folders to exclude, and an optional
+-- `extensions` sub-table that contains raw file extensions to exclude. Any
+-- patterns starting with '!' exclude files and folders that do not match the
+-- pattern that follows.
 -- @param dir The directory path to iterate over.
 -- @param f Function to call with each full file path found. If *f* returns
 --   `false` explicitly, iteration ceases.
diff --git a/doc/06_AdeptEditing.md b/doc/06_AdeptEditing.md
index f27df547..9356f0e6 100644
--- a/doc/06_AdeptEditing.md
+++ b/doc/06_AdeptEditing.md
@@ -14,7 +14,7 @@ Usually, brace ('(', '[', '{') and quote (''', '"') characters go
 together in pairs. Textadept automatically inserts the complement character of
 any user-typed opening brace or quote character and allows the user to
 subsequently type over it. Similarly, the editor deletes the complement when
-you press `Bksp` (`⌫` on Mac OSX | `Bksp` in curses) over the first. The
+you press `Bksp` (`⌫` on Mac OSX | `Bksp` in curses) over the typed one. The
 [preferences][] page details how to configure or disable these features.
 
 [preferences]: 08_Preferences.html#Generic
diff --git a/doc/08_Preferences.md b/doc/08_Preferences.md
index a6e0a09f..36bab575 100644
--- a/doc/08_Preferences.md
+++ b/doc/08_Preferences.md
@@ -167,8 +167,8 @@ spaces by default, your *~/.textadept/properties.lua* would contain:
 (Remember that in order to have per-filetype properties, you need to have a
 [language module][].)
 
-Textadept's *properties.lua* is a good reference to see available properties to
-set. It also has many commented out properties that you can copy to your
+Textadept's *properties.lua* is a good "quick reference" for configurable
+properties. It also has many commented out properties that you can copy to your
 *~/.textadept/properties.lua* and uncomment to turn on or change the value of.
 Use [Adeptsense][] to view a property's documentation or read the [LuaDoc][].
 
diff --git a/modules/textadept/adeptsense.lua b/modules/textadept/adeptsense.lua
index fc1431c9..90cd952e 100644
--- a/modules/textadept/adeptsense.lua
+++ b/modules/textadept/adeptsense.lua
@@ -112,11 +112,12 @@ local M = {}
 -- ### Completion Lists
 --
 -- Even though your Adeptsense now understands the basic syntax of your
--- programming language, it is not smart enough to parse code to generate lists
--- of function and field completions for classes. Instead, you must supply this
--- information to your Adeptsense's [`completions`](#completions) table. The
--- table contains string class names assigned to tables that themselves contain
--- `functions` and `fields` completion tables. Here is the general form:
+-- programming language, it is not smart enough to parse code in order to
+-- generate lists of function and field completions for classes. Instead, you
+-- must supply this information to your Adeptsense's
+-- [`completions`](#completions) table. The table contains string class names
+-- assigned to tables that themselves contain `functions` and `fields`
+-- completion tables. Here is the general form:
 --
 --     M.sense.completions = {
 --       ['class1'] = {
diff --git a/modules/textadept/editing.lua b/modules/textadept/editing.lua
index 877354a9..bb096b89 100644
--- a/modules/textadept/editing.lua
+++ b/modules/textadept/editing.lua
@@ -418,12 +418,9 @@ function M.select_paragraph()
 end
 
 ---
--- Selects indented text blocks intelligently.
--- If no block of text is selected, all text with the current level of
--- indentation is selected. If a block of text is selected and the lines
--- immediately above and below it are one indentation level lower, they are
--- added to the selection. In all other cases, the behavior is the same as if no
--- text is selected.
+-- Selects all text with the current level of indentation.
+-- If a text block is selected and the lines immediately above and below it are
+-- one indentation level lower, adds those lines to the selection.
 -- @name select_indented_block
 function M.select_indented_block()
   local buffer = buffer
@@ -505,15 +502,15 @@ function M.highlight_word()
 end
 
 ---
--- Passes selected or all buffer text to string shell command *command* as
--- standard input (stdin) and replaces the input text with the command's
+-- Passes the selected text or all buffer text to string shell command *command*
+-- as standard input (stdin) and replaces the input text with the command's
 -- standard output (stdout).
 -- Standard input is 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.
+-- containing the selection is passed as stdin. However, if the end of the
+-- selection is at the beginning of a line, only the line ending characters from
+-- the previous line are included. 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.
diff --git a/modules/textadept/find.lua b/modules/textadept/find.lua
index 177e85e8..4a9e6054 100644
--- a/modules/textadept/find.lua
+++ b/modules/textadept/find.lua
@@ -10,16 +10,16 @@ local M = ui.find
 -- @field replace_entry_text (string)
 --   The text in the replace entry.
 -- @field match_case (bool)
---   Searches are case-sensitive.
+--   Match the search text case sensitively.
 --   The default value is `false`.
 -- @field whole_word (bool)
---   Match only whole-words in searches.
+--   Match the search text surrounded by non-word characters in searches.
 --   The default value is `false`.
 -- @field lua (bool)
---   Interpret search text as a Lua pattern.
+--   Interpret the search text as a Lua pattern.
 --   The default value is `false`.
 -- @field in_files (bool)
---   Search for the text in a list of files.
+--   Find the search text in a list of files.
 --   The default value is `false`.
 -- @field find_label_text (string, Write-only)
 --   The text of the "Find" label.
@@ -80,11 +80,11 @@ local preferred_view
 ---
 -- The table of Lua patterns matching files and folders to exclude when finding
 -- in files.
--- Each filter string is a pattern that matches filenames to exclude, with
--- patterns matching folders to exclude listed in a `folders` sub-table.
--- Patterns starting with '!' exclude files and folders that do not match the
--- pattern that follows. Use a table of raw file extensions assigned to an
--- `extensions` key for fast filtering by extension.
+-- The filter contains Lua patterns that match filenames to exclude, an optional
+-- `folders` sub-table that contains patterns matching folders to exclude, and
+-- an optional `extensions` sub-table that contains raw file extensions to
+-- exclude. Any patterns starting with '!' exclude files and folders that do not
+-- match the pattern that follows.
 -- The default value is `lfs.FILTER`, a filter for common binary file extensions
 -- and version control folders.
 -- @see find_in_files
@@ -326,7 +326,7 @@ events.connect(events.REPLACE_ALL, replace_all)
 -- Returns whether or not the given buffer is a files found buffer.
 local function is_ff_buf(buf) return buf._type == _L['[Files Found Buffer]'] end
 ---
--- Goes to the source of the find in files search result on line number *line*
+-- Jumps to the source of the find in files search result on line number *line*
 -- in the files found buffer, or if `nil`, the next or previous search result
 -- depending on boolean *next*.
 -- @param line The line number in the files found buffer that contains the
diff --git a/modules/textadept/run.lua b/modules/textadept/run.lua
index d6f9f421..32823c47 100644
--- a/modules/textadept/run.lua
+++ b/modules/textadept/run.lua
@@ -187,7 +187,7 @@ M.error_patterns = {--[[ANTLR]]'^error%(%d+%): (.-):(%d+):%d+: (.+)$','^warning%
 -- Returns whether or not the given buffer is a message buffer.
 local function is_msg_buf(buf) return buf._type == _L['[Message Buffer]'] end
 ---
--- Goes to the source of the recognized compile/run warning or error on line
+-- Jumps to the source of the recognized compile/run warning or error on line
 -- number *line* in the message buffer or the next or previous recognized
 -- warning or error depending on boolean *next*.
 -- Displays an annotation with the warning or error message, if available.
diff --git a/modules/textadept/session.lua b/modules/textadept/session.lua
index 2419a822..d470ce5a 100644
--- a/modules/textadept/session.lua
+++ b/modules/textadept/session.lua
@@ -29,8 +29,8 @@ M.SAVE_ON_QUIT = true
 M.MAX_RECENT_FILES = 10
 
 ---
--- Loads Textadept session file *filename* or prompts the user to selectone,
--- returning `true` if the session file was opened and read.
+-- Loads Textadept session file *filename* or user-selected file, returning
+-- `true` if the session file was opened and read.
 -- Textadept restores split views, opened buffers, cursor information, and
 -- recent files.
 -- @param filename Optional absolute path to the session file to load. If `nil`,
diff --git a/properties.lua b/properties.lua
index bb0c8c42..117ccb8f 100644
--- a/properties.lua
+++ b/properties.lua
@@ -146,8 +146,8 @@ buffer.call_tip_use_style = buffer.tab_width *
 
 -- Folding.
 buffer.property['fold'] = '1'
-buffer.property['fold.by.indentation'] = '0'
-buffer.property['fold.line.comments'] = '0'
+--buffer.property['fold.by.indentation'] = '1'
+--buffer.property['fold.line.comments'] = '1'
 buffer.automatic_fold = buffer.AUTOMATICFOLD_SHOW + buffer.AUTOMATICFOLD_CLICK +
                         buffer.AUTOMATICFOLD_CHANGE
 buffer.fold_flags = not CURSES and buffer.FOLDFLAG_LINEAFTER_CONTRACTED or 0