More LuaDoc updates.

1 files changed, 82 insertions, 86 deletions

diff --git a/core/.buffer.luadoc b/core/.buffer.luadoc
index 711ab255..a9e9b8c0 100644
--- a/core/.buffer.luadoc
+++ b/core/.buffer.luadoc
@@ -35,7 +35,7 @@
 -- @field all_lines_visible (bool, Read-only)
 --   Whether or not all lines are visible.
 -- @field anchor (number)
---   The position of the anchor.
+--   The anchor's position.
 -- @field annotation_lines (table, Read-only)
 --   Table of the number of annotation lines for line numbers starting from
 --   zero.
@@ -149,24 +149,23 @@
 --   bitmap to the screen.
 --   The default value is `true`.
 -- @field call_tip_fore_hlt (number, Write-only)
---   The foreground color, in "0xBBGGRR" format, of the highlighted part of
---   call tips.
+--   The call tip's highlighted text foreground color, in "0xBBGGRR" format.
 -- @field call_tip_position (boolean)
 --   Display the call tip above instead of below the text.
 --   The default value is `false`.
 -- @field call_tip_use_style (number)
---   The pixel size of tab characters in call tips.
+--   The pixel width of tab characters in call tips.
 --   When non-zero, also enables the use of style number `buffer.STYLE_CALLTIP`
 --   instead of `buffer.STYLE_DEFAULT` for call tip styles.
 --   The default value is `0`.
 -- @field caret_fore (number)
---   The foreground color, in "0xBBGGRR" format, of the caret.
+--   The caret's foreground color, in "0xBBGGRR" format.
 -- @field caret_line_back (number)
 --   The background color, in "0xBBGGRR" format, of the line containing the
 --   caret.
 -- @field caret_line_back_alpha (number)
---   The background alpha value, ranging from `0` (transparent) to `255`
---   (opaque), of the caret line.
+--   The caret line's background alpha value, ranging from `0` (transparent) to
+--   `255` (opaque).
 --   The default value is `buffer.ALPHA_NOALPHA`, for no alpha.
 -- @field caret_line_visible (bool)
 --   Color the background of the line containing the caret a different color.
@@ -180,7 +179,7 @@
 --   A value of `0` stops blinking.
 --   The default value is `500`.
 -- @field caret_sticky (number)
---   The preferred horizontal position of the caret when moving between lines.
+--   The caret's preferred horizontal position when moving between lines.
 --
 --   * `buffer.CARETSTICKY_OFF`
 --     Use the same position as on the previous line.
@@ -193,7 +192,7 @@
 --
 --   The default value is `buffer.CARETSTICKY_OFF`.
 -- @field caret_style (number)
---   The visual style of the caret.
+--   The caret's visual style.
 --
 --   * `buffer.CARETSTYLE_INVISIBLE`
 --     No caret.
@@ -204,8 +203,7 @@
 --
 --   The default value is `buffer.CARETSTYLE_LINE`.
 -- @field caret_width (number)
---   The pixel width of the caret in insert mode, either `0`, `1`, `2`, or `3`,
---   and only applicable to line carets.
+--   The line caret's pixel width in insert mode, either `0`, `1`, `2`, or `3`.
 --   The default value is `1`.
 -- @field char_at (table, Read-only)
 --   Table of character bytes at positions starting from zero.
@@ -213,7 +211,7 @@
 --   Table of column numbers, taking tab widths into account, for positions
 --   starting from zero.
 -- @field current_pos (number)
---   The position of the caret.
+--   The caret's position.
 --   When set, does not scroll the caret into view.
 -- @field cursor (number)
 --   The display cursor type.
@@ -248,15 +246,14 @@
 --     [`buffer.edge_column`](#edge_column) to
 --     [`buffer.edge_colour`](#edge_colour).
 -- @field encoding (string or nil)
---   The string encoding of the file on the hard drive or `nil` for binary
---   files.
+--   The string encoding of the file, or `nil` for binary files.
 -- @field encoding_bom (string)
---   The byte-order mark, if any, of the file encoding.
+--   The byte-order mark, if any, of the file.
 -- @field end_at_last_line (bool)
 --   Disable scrolling past the last line.
 --   The default value is `true`.
 -- @field end_styled (number, Read-only)
---   The position of the last correctly styled character.
+--   The last correctly styled character's position.
 -- @field eol_mode (number)
 --   The current end of line mode. Changing the mode does not convert existing
 --   line endings. Use [`buffer:convert_eols()`](#convert_eols) to do so.
@@ -277,7 +274,7 @@
 --   The amount of pixel padding below line text.
 --   The default is `0`.
 -- @field filename (string)
---   The absolute path to the file associated with the buffer.
+--   The absolute file path associated with the buffer.
 -- @field first_visible_line (number)
 --   The line number of the line at the top of the view, starting from zero.
 -- @field fold_expanded (table)
@@ -286,7 +283,7 @@
 --   Setting expanded fold states does not toggle folds; it only updates fold
 --   margin markers. Use [`buffer:toggle_fold()`](#toggle_fold) instead.
 -- @field fold_flags (number)
---   Bit-mask of options for drawing folding lines.
+--   Bit-mask of folding lines to draw in the buffer.
 --
 --   * `buffer.FOLDFLAG_LINEBEFORE_EXPANDED`
 --     Draw lines above expanded folds.
@@ -300,7 +297,7 @@
 --   The default value is `0`.
 -- @field fold_level (table)
 --   Table of fold level bit-masks for line numbers starting from zero.
---   Fold level masks are composed of an integer level combined with any of the
+--   Fold level masks comprise of an integer level combined with any of the
 --   following bits:
 --
 --   * `buffer.FOLDLEVELBASE`
@@ -339,8 +336,8 @@
 --   * `buffer.IV_REAL`
 --     Draw guides only within indentation whitespace.
 --   * `buffer.IV_LOOKFORWARD`
---     Draw guides beyond the current line up to the level of the next non-empty
---     line, but with an additional level if the previous non-empty line is a
+--     Draw guides beyond the current line up to the next non-empty line's
+--     level, but with an additional level if the previous non-empty line is a
 --     fold header.
 --   * `buffer.IV_LOOKBOTH`
 --     Draw guides beyond the current line up to either the level of the
@@ -469,8 +466,8 @@
 --   * `buffer.MARGINOPTION_NONE`
 --     None.
 --   * `buffer.MARGINOPTION_SUBLINESELECT`
---     Select only the sub-line of the wrapped line, rather than the entire
---     line, on margin click.
+--     Select only the wrapped line's sub-line, rather than the entire line, on
+--     margin click.
 --
 --   The default value is `buffer.MARGINOPTION_NONE`.
 -- @field margin_right (number)
@@ -572,13 +569,13 @@
 --   Whether or not the buffer is read-only.
 --   The default value is `false`.
 -- @field rectangular_selection_anchor (number)
---   The position of the anchor of the rectangular selection.
+--   The rectangular selection's anchor position.
 -- @field rectangular_selection_anchor_virtual_space (number)
---   The amount of virtual space for the anchor of the rectangular selection.
+--   The amount of virtual space for the rectangular selection's anchor.
 -- @field rectangular_selection_caret (number)
---   The position of the caret of the rectangular selection.
+--   The rectangular selection's caret position.
 -- @field rectangular_selection_caret_virtual_space (number)
---   The amount of virtual space for the caret of the rectangular selection.
+--   The amount of virtual space for the rectangular selection's caret.
 -- @field rectangular_selection_modifier (number)
 --   The modifier key used in combination with a mouse drag to create a
 --   rectangular selection.
@@ -607,7 +604,7 @@
 --   [`buffer:marker_define_rgba_image()`](#marker_define_rgba_image) and
 --   [`buffer:register_rgba_image()`](#register_rgba_image).
 -- @field scroll_width (number)
---   The horizontal scroll pixel width.
+--   The horizontal scrolling 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
@@ -665,11 +662,11 @@
 --     Represents character *x*, ignoring any special meaning it may have by
 --     itself.
 -- @field sel_alpha (number)
---   The alpha value, ranging from `0` (transparent) to `255` (opaque), of the
---   selection.
+--   The selection's alpha value, ranging from `0` (transparent) to `255`
+--   (opaque).
 --   The default value is `buffer.ALPHA_NOALPHA`, for no alpha.
 -- @field sel_eol_filled (bool)
---   Extend the selection to the right margin of the view.
+--   Extend the selection to the view's right margin.
 --   The default value is `false`.
 -- @field selection_empty (bool, Read-only)
 --   Whether or not no text is selected.
@@ -746,8 +743,8 @@
 --   but ranges containing read-only text are deletable.
 -- @field style_eol_filled (table)
 --   Table of flags indicating whether or not the background colors of styles
---   whose characters occur last on lines extend all the way to the right margin
---   of the view for style numbers from `0` to `255`.
+--   whose characters occur last on lines extend all the way to the view's right
+--   margin for style numbers from `0` to `255`.
 --   The default values are `false`.
 -- @field style_font (table)
 --   Table of string font faces of text within styles for style numbers from
@@ -874,7 +871,7 @@
 --
 --   The default value is `buffer.WRAP_NONE`.
 -- @field wrap_start_indent (number)
---   The number of spaces to indent wrapped lines by if
+--   The number of spaces of indentation to display wrapped lines with if
 --   [`buffer.wrap_indent_mode`](#wrap_indent_mode) is
 --   `buffer.WRAP_INDENT_FIXED`.
 --   The default value is `0`.
@@ -888,7 +885,7 @@
 --   * `buffer.WRAPVISUALFLAG_START`
 --     Show visual flag at the beginning of the sub-line.
 --   * `buffer.WRAPVISUALFLAG_MARGIN`
---     Show visual flag in the line number margin of the sub-line.
+--     Show visual flag in the sub-line's line number margin.
 --
 --   The default value is `buffer.WRAPVISUALFLAG_NONE`.
 -- @field wrap_visual_flags_location (number)
@@ -1121,13 +1118,13 @@ function can_undo(buffer) end
 function cancel(buffer) end
 
 ---
--- Tells the lexer to re-process the range of text between *start_pos* and
+-- Tells the lexer to reprocess the range of text between *start_pos* and
 -- *end_pos*.
 -- @param buffer The global buffer.
 -- @param start_pos The start position of the range of text in *buffer* to
---   re-process.
+--   reprocess.
 -- @param end_pos The end position of the range of text in *buffer* to
---   re-process.
+--   reprocess.
 function change_lexer_state(buffer, start_pos, end_pos) end
 
 ---
@@ -1182,8 +1179,8 @@ function char_right_extend(buffer) end
 function char_right_rect_extend(buffer) end
 
 ---
--- Sets the preferred horizontal position of the caret when moving between
--- lines to the current position.
+-- Identifies the current horizontal caret position as the caret's preferred
+-- horizontal position when moving between lines.
 -- @param buffer The global buffer.
 -- @see caret_sticky
 function choose_caret_x(buffer) end
@@ -1289,12 +1286,12 @@ function count_characters(buffer, start_pos, end_pos) end
 function cut(buffer) end
 
 ---
--- Deletes text from the caret to the beginning of the line.
+-- Deletes the range of text from the caret to the beginning of the line.
 -- @param buffer The global buffer.
 function del_line_left(buffer) end
 
 ---
--- Deletes text from the caret to the end of the line.
+-- Deletes the range of text from the caret to the end of the line.
 -- @param buffer The global buffer.
 function del_line_right(buffer) end
 
@@ -1331,7 +1328,7 @@ function delete_back(buffer) end
 function delete_back_not_line(buffer) end
 
 ---
--- Deletes the buffer's text from position *pos* to *pos* + *length*.
+-- Deletes the range of text from position *pos* to *pos* + *length*.
 -- @param buffer The global buffer.
 -- @param pos The start position of the range of text in *buffer* to delete.
 -- @param length The number of characters in the range of text to delete.
@@ -1459,7 +1456,7 @@ function fold_line(buffer, line, action) end
 function form_feed(buffer) end
 
 ---
--- Returns the current line's text and the index of the caret on the line,
+-- Returns the current line's text and the caret's position on the line,
 -- starting from zero.
 -- @param buffer The global buffer.
 -- @return string, number
@@ -1597,8 +1594,8 @@ function home_wrap_extend(buffer) end
 function indicator_all_on_for(buffer, pos) end
 
 ---
--- Clears indicator `buffer.indicator_current` over the range of text from
--- position *pos* to *pos* + *clear_length*.
+-- Clears indicator number `buffer.indicator_current` over the range of text
+-- from position *pos* to *pos* + *clear_length*.
 -- @param buffer The global buffer.
 -- @param pos The start position of the range of text in *buffer* to clear
 --   indicators over.
@@ -1615,8 +1612,8 @@ function indicator_clear_range(buffer, pos, clear_length) end
 function indicator_end(buffer, indicator, pos) end
 
 ---
--- Sets indicator number `buffer.indicator_current` over the range of text from
--- position *pos* to *pos* + *fill_length*.
+-- Fills the range of text from position *pos* to *pos* + *fill_length* with
+-- indicator number `buffer.indicator_current`.
 -- @param buffer The global buffer.
 -- @param pos The start position of the range of text in *buffer* to set
 --   indicators over.
@@ -1758,7 +1755,7 @@ function line_scroll_down(buffer) end
 function line_scroll_up(buffer) end
 
 ---
--- Switches the current line with the previous one.
+-- Swaps the current line with the previous one.
 -- @param buffer The global buffer.
 function line_transpose(buffer) end
 
@@ -1798,7 +1795,7 @@ function lines_split(buffer, pixel_width) end
 function lower_case(buffer) end
 
 ---
--- Clears margin text on all lines.
+-- Clears the text in text margins on all lines.
 -- @param buffer The global buffer.
 function margin_text_clear_all(buffer) end
 
@@ -1958,12 +1955,12 @@ function marker_symbol_defined(buffer, marker_num) end
 function move_caret_inside_view(buffer) end
 
 ---
--- Moves the selected lines down one line.
+-- Shifts the selected lines down one line.
 -- @param buffer The global buffer.
 function move_selected_lines_down(buffer) end
 
 ---
--- Moves the selected lines up one line.
+-- Shifts the selected lines up one line.
 -- @param buffer The global buffer.
 function move_selected_lines_up(buffer) end
 
@@ -2033,8 +2030,8 @@ function para_up(buffer) end
 function para_up_extend(buffer) end
 
 ---
--- Pastes the contents of the clipboard into the buffer, replacing any selected
--- text depending on `buffer.multi_paste`.
+-- Pastes the clipboard's contents into the buffer, replacing any selected text
+-- depending on `buffer.multi_paste`.
 -- @param buffer The global buffer.
 function paste(buffer) end
 
@@ -2126,15 +2123,15 @@ function replace_target(buffer, text) end
 ---
 -- Replaces the text in the target range with string *text* but first replaces
 -- any "\d" sequences with the value of tag match number *d* from the regular
--- expression (or the entire match for *d* = 0), and then returns the length of
--- the replacement text.
+-- expression (or the entire match for *d* = 0), and then returns the
+-- replacement text's length.
 -- @param buffer The global buffer.
 -- @param text The text to replace the target range with.
 -- @return number
 function replace_target_re(buffer, text) end
 
 ---
--- Sets the next additional selection to be the main selection.
+-- Taps the next additional selection to be the main selection.
 -- @param buffer The global buffer.
 function rotate_selection(buffer) end
 
@@ -2168,8 +2165,8 @@ function scroll_to_end(buffer) end
 function scroll_to_start(buffer) end
 
 ---
--- Sets the position `buffer:search_next()` and `buffer:search_prev()` begin at
--- to the caret position.
+-- Anchors the position `buffer:search_next()` and `buffer:search_prev()` begin
+-- at to the caret position.
 -- @param buffer The global buffer.
 function search_anchor(buffer) end
 
@@ -2186,8 +2183,8 @@ function search_in_target(buffer, text) end
 
 ---
 -- Searches for and selects the first occurrence of string *text* starting at
--- the search anchor using search flags *flags*, returning the position of the
--- occurrence or `-1`.
+-- the search anchor using search flags *flags*, returning the occurrence's
+-- position or `-1`.
 -- Selected text is not scrolled into view.
 -- @param buffer The global buffer.
 -- @param flags The search flags to use. See `buffer.search_flags`.
@@ -2198,8 +2195,8 @@ function search_next(buffer, flags, text) end
 
 ---
 -- Searches for and selects the last occurrence of string *text* before the
--- search anchor using search flags *flags*, returning the position of the
--- occurrence or `-1`.
+-- search anchor using search flags *flags*, returning the occurrence's position
+-- or `-1`.
 -- @param buffer The global buffer.
 -- @param flags The search flags to use. See `buffer.search_flags`.
 -- @param text The text to search for.
@@ -2235,15 +2232,15 @@ function set_chars_default(buffer) end
 function set_empty_selection(buffer, pos) end
 
 ---
--- Overrides the default color of the fold margin with *color*, in "0xBBGGRR"
--- format, if *use_setting* is `true`.
+-- Overrides the fold margin's default color with *color*, in "0xBBGGRR" format,
+-- if *use_setting* is `true`.
 -- @param buffer The global buffer.
 -- @param use_setting Whether or not to use *color*.
 -- @param color The color in "0xBBGGRR" format.
 function set_fold_margin_colour(buffer, use_setting, color) end
 
 ---
--- Overrides the default highlight color of the fold margin with *color*, in
+-- Overrides the fold margin's default highlight color with *color*, in
 -- "0xBBGGRR" format, if *use_setting* is `true`.
 -- @param buffer The global buffer.
 -- @param use_setting Whether or not to use *color*.
@@ -2272,7 +2269,7 @@ function set_hotspot_active_fore(buffer, use_setting, color) end
 function set_save_point(buffer) end
 
 ---
--- Selects the buffer's text between positions *start_pos* and *end_pos*,
+-- Selects the range of text between positions *start_pos* and *end_pos*,
 -- scrolling the selected text into view.
 -- @param buffer The global buffer.
 -- @param start_pos The start position of the range of text in *buffer* to
@@ -2283,7 +2280,7 @@ function set_save_point(buffer) end
 function set_sel(buffer, start_pos, end_pos) end
 
 ---
--- Overrides the default background color of the selection with *color*, in
+-- Overrides the selection's default background color with *color*, in
 -- "0xBBGGRR" format, if *use_setting* is `true`.
 -- @param buffer The global buffer.
 -- @param use_setting Whether or not to use *color*.
@@ -2291,7 +2288,7 @@ function set_sel(buffer, start_pos, end_pos) end
 function set_sel_back(buffer, use_setting, color) end
 
 ---
--- Overrides the default foreground color of the selection with *color*, in
+-- Overrides the selection's default foreground color with *color*, in
 -- "0xBBGGRR" format, if *use_setting* is `true`.
 -- @param buffer The global buffer.
 -- @param use_setting Whether or not to use *color*.
@@ -2299,7 +2296,7 @@ function set_sel_back(buffer, use_setting, color) end
 function set_sel_fore(buffer, use_setting, color) end
 
 ---
--- Selects the buffer's text between positions *start_pos* to *end_pos*,
+-- Selects the range of text between positions *start_pos* to *end_pos*,
 -- removing all other selections.
 -- @param buffer The global buffer.
 -- @param end_pos The caret position of the range of text to select in *buffer*.
@@ -2308,7 +2305,7 @@ function set_sel_fore(buffer, use_setting, color) end
 function set_selection(buffer, end_pos, start_pos) end
 
 ---
--- Sets the style of the next *length* characters, from the current styling
+-- Assigns the style of the next *length* characters, from the current styling
 -- position, to style number *style*, in the range from `0` to `255`, and
 -- increments the styling position by *length*.
 -- @param buffer The global buffer.
@@ -2377,7 +2374,7 @@ function set_y_caret_policy(buffer, caret_policy, caret_slop) end
 function show_lines(buffer, start_line, end_line) end
 
 ---
--- Begin styling at position *position* with styling bit-mask *styling_mask*.
+-- Begins styling at position *position* with styling bit-mask *styling_mask*.
 -- *styling_mask* specifies which style bits can be set with
 -- `buffer:set_styling()`.
 -- @param buffer The global buffer.
@@ -2410,8 +2407,7 @@ function stuttered_page_up(buffer) end
 function stuttered_page_up_extend(buffer) end
 
 ---
--- Sets all styles to have the same properties as
--- `buffer.STYLE_DEFAULT`.
+-- Reverts all styles to have the same properties as `buffer.STYLE_DEFAULT`.
 -- @param buffer The global buffer.
 function style_clear_all(buffer) end
 
@@ -2421,7 +2417,7 @@ function style_clear_all(buffer) end
 function style_reset_default(buffer) end
 
 ---
--- Swaps the beginning and end positions of the main selection.
+-- Swaps the main selection's beginning and end positions.
 -- @param buffer The global buffer.
 function swap_main_anchor_caret(buffer) end
 
@@ -2432,8 +2428,8 @@ function swap_main_anchor_caret(buffer) end
 function tab(buffer) end
 
 ---
--- Sets the beginning and end positions of the target range to be the beginning
--- and end positions of the main selection.
+-- Defines the target range's beginning and end positions as the beginning and
+-- end positions of the main selection, respectively.
 -- @param buffer The global buffer.
 function target_from_selection(buffer) end
 
@@ -2551,8 +2547,8 @@ function visible_from_doc_line(buffer, line) end
 ---
 -- Returns the position of the end of the word at position *pos*.
 -- `buffer.word_chars` contains word characters. If *pos* has a non-word
--- character to its right and *only_word_chars* is `false`, returns the position
--- of the first word character.
+-- character to its right and *only_word_chars* is `false`, returns the first
+-- word character's position.
 -- @param buffer The global buffer.
 -- @param pos The position in *buffer* of the word.
 -- @param only_word_chars If `true`, stops searching at the first non-word
@@ -2645,8 +2641,8 @@ function word_right_extend(buffer) end
 ---
 -- Returns the position of the beginning of the word at position *pos*.
 -- `buffer.word_chars` contains word characters. If *pos* has a non-word
--- character to its left and *only_word_chars* is `false`, returns the position
--- of the last word character.
+-- character to its left and *only_word_chars* is `false`, returns the last word
+-- character's position.
 -- @param buffer The global buffer.
 -- @param pos The position in *buffer* of the word.
 -- @param only_word_chars If `true`, stops searching at the first non-word
@@ -2701,15 +2697,15 @@ function delete(buffer) end
 function new() end
 
 ---
--- Returns the buffer's text between positions *start_pos* and *end_pos*.
+-- Returns the range of text between positions *start_pos* and *end_pos*.
 -- @param buffer The global buffer.
 -- @param start_pos The start position of the range of text to get in *buffer*.
 -- @param end_pos The end position of the range of text to get in *buffer*.
 function text_range(buffer, start_pos, end_pos) end
 
 ---
--- Returns the name of the lexer used by the buffer, or the name of the lexer
--- under the caret in a multiple-language lexer if *current* is `true`.
+-- Returns the buffer's lexer name, or the name of the lexer under the caret in
+-- a multiple-language lexer if *current* is `true`.
 -- @param buffer The global buffer.
 -- @param current Whether or not to get the lexer at the current caret position
 --   in multi-language lexers. The default is `false` and returns the parent
@@ -2717,8 +2713,8 @@ function text_range(buffer, start_pos, end_pos) end
 function get_lexer(buffer, current) end
 
 ---
--- Sets the name of the lexer used by the buffer to *lang* or the auto-detected
--- language and then loads the appropriate language module if the module exists.
+-- Changes the buffer's lexer name to *lang* or the auto-detected language and
+-- then loads the appropriate language module if the module exists.
 -- @param buffer The global buffer.
 -- @param lang Optional string language name to set. If `nil`, attempts to
 --   auto-detect the buffer's language.