Rewrote LuaDoc.

11 files changed, 1440 insertions, 1243 deletions

diff --git a/core/.buffer.luadoc b/core/.buffer.luadoc
index 54b891a7..fe1cfa3b 100644
--- a/core/.buffer.luadoc
+++ b/core/.buffer.luadoc
@@ -10,598 +10,611 @@
 --
 -- [buffer]: _G.html#buffer
 -- @field additional_caret_fore (number)
---   The foreground color of additional carets in "0xBBGGRR" format.
+--   The foreground color, in "0xBBGGRR" format, of additional carets.
 -- @field additional_carets_blink (bool)
---   Whether additional carets will blink.
+--   Allow additional carets to blink.
+--   The default value is `true`.
 -- @field additional_carets_visible (bool)
---   Whether additional carets are visible.
+--   Display additional carets.
+--   The default value is `true`.
 -- @field additional_sel_alpha (number)
---   The alpha of additional selections. Alpha ranges from `0` (transparent) to
---   `255` (opaque) or `256` for no alpha.
+--   The alpha value, ranging from `0` (transparent) to `255` (opaque), of
+--   additional selections.
+--   The default value is `256`, for no alpha.
 -- @field additional_sel_back (number)
---   The background color of additional selections in "0xBBGGRR" format.
---   `buffer:set_sel_back(true, ...)` must have been called previously for this
---   to have an effect.
+--   The background color, in "0xBBGGRR" format, of additional selections.
+--   This field has no effect when calling `buffer:set_sel_back(false, ...)`.
 -- @field additional_sel_fore (number)
---   The foreground color of additional selections in "0xBBGGRR" format.
---   `buffer:set_sel_fore(true, ...)` must have been called previously for this
---   to have an effect.
+--   The foreground color, in "0xBBGGRR" format, of additional selections.
+--   This field has no effect when calling `buffer:set_sel_fore(false, ...)`.
 -- @field additional_selection_typing (bool)
---   Whether typing can be performed into multiple selections.
+--   Type into multiple selections.
+--   The default value is `false`.
+-- @field all_lines_visible (bool, Read-only)
+--   Whether or not all lines in the buffer are visible.
 -- @field anchor (number)
---   The position of the opposite end of the selection to the caret.
+--   The position of the beginning of the selected text.
 -- @field annotation_lines (table, Read-only)
---   Table of the number of annotation lines for lines starting from zero.
+--   Table of the number of annotation lines for line numbers starting from
+--   zero.
 -- @field annotation_style (table)
---   Table of style numbers for annotations for lines starting at zero.
+--   Table of style numbers for annotations for line numbers starting from zero.
 --   Only some style attributes are active in annotations: font,
 --   size/size_fractional, bold/weight, italics, fore, back, and character_set.
 -- @field annotation_style_offset (number)
---   The start of the range of style numbers used for annotations.
+--   The beginning of the range of style numbers used for annotations.
 --   Annotation styles may be completely separated from standard text styles by
 --   setting a style offset. For example, setting this to `512` would allow the
 --   annotation styles to be numbered from `512` upto `767` so they do not
 --   overlap styles set by lexers (or margins if margins offset is `256`). Each
---   style number set with `buffer.annotation_style` has the offset added before
+--   style number set with `annotation_style` has the offset added before
 --   looking up the style.
+--   The default value is `0`.
 -- @field annotation_text (table)
---   Table of annotation text for lines starting from zero.
+--   Table of annotation text for line numbers starting from zero.
 -- @field annotation_visible (number)
---   The visibility of annotations.
+--   The annotation visibility mode.
 --
 --   * `_SCINTILLA.constants.ANNOTATION_HIDDEN` (0)
---     Annotations are not displayed.
+--     Annotations are invisible.
 --   * `_SCINTILLA.constants.ANNOTATION_STANDARD` (1)
---     Annotations are drawn left justified with no adornment.
+--     Draw annotations left-justified with no decoration.
 --   * `_SCINTILLA.constants.ANNOTATION_BOXED` (2)
---     Annotations are indented to match the text and are surrounded by a box.
+--     Indent annotations to match the text and outline with a box.
+--
+--   The default value is `0`.
 -- @field auto_c_auto_hide (bool)
---   Whether or not autocompletion is hidden automatically when nothing matches.
---   By default, the list is cancelled if there are no viable matches (the user
---   has typed characters that no longer match a list entry).
+--   Automatically hide the autocompletion list when no entries match typed
+--   text.
+--   The default value is `true`.
 -- @field auto_c_cancel_at_start (bool)
---   Whether auto-completion is cancelled by backspacing to a position before
---   where the box was created.
---   If `false`, the list is not cancelled until the caret moves at least one
---   character before the word being completed. If `true`, cancel if the user
---   backspaces to a position before where it was created.
--- @field auto_c_case_insensitive (int)
---   Auto-completion case insensitive behavior.
---   When autocompletion is set to ignore case (`buffer.auto_c_ignore_case`), by
---   default it will nonetheless select the first list member that matches in a
---   case sensitive way to entered characters.
+--   Cancel autocompletion when backspacing to a position before where
+--   autocompletion started or before the word being completed.
+--   The default value is `true`, to cancel when backspacing before where
+--   autocompletion started.
+-- @field auto_c_case_insensitive_behaviour (number)
+--   The behavior setting for case insensitive autocompletion when
+--   [`buffer.auto_c_ignore_case`](#auto_c_ignore_case) is `true`.
 --
 --   * `_SCINTILLA.constants.SC_CASEINSENSITIVEBEHAVIOR_RESPECTCASE` (0)
---     Prefer case-sensitive matches.
+--     Prefer to select case-sensitive matches.
 --   * `_SCINTILLA.constants.SC_CASEINSENSITIVEBEHAVIOR_IGNORECASE` (1)
 --     No preference.
+--
+--   The default value is `0`.
 -- @field auto_c_choose_single (bool)
---   Whether a single item auto-completion list automatically choose the item.
---   The default is to display the list even if there is only a single item.
+--   Automatically choose the item in a single-item autocompletion list.
+--   The default value is `false`.
 -- @field auto_c_current (number, Read-only)
---   The currently selected item position in the auto-completion list.
+--   The index of the currently selected item in the autocompletion list.
 -- @field auto_c_current_text (string, Read-only)
---   The currently selected item text in the auto-completion list.
+--   The text of the currently selected item in the autocompletion list.
 -- @field auto_c_drop_rest_of_word (bool)
---   Whether or not autocompletion deletes any word characters after the
---   inserted text upon completion.
---   The default is `false`.
+--   Delete word characters after autocompleted text.
+--   The default value is `false`.
 -- @field auto_c_fill_ups (string, Write-only)
---   A set of characters that when typed will cause the autocompletion to choose
---   the selected item.
---   By default, no fillup characters are set.
+--   A set of characters that choose the currently selected item in an
+--   autocompletion list when typed.
+--   The default value is an empty string.
 -- @field auto_c_ignore_case (bool)
---   Whether case is significant when performing auto-completion searches.
---   By default, matching of characters to list members is case sensitive.
+--   Ignore case when searching an autocompletion list for matches.
+--   The default value is `false`.
 -- @field auto_c_max_height (number)
---   The maximum height, in rows, of auto-completion and user lists.
---   The default is 5 rows.
+--   The maximum number of items to show in autocompletion and user lists. The
+--   default value is `5`.
 -- @field auto_c_max_width (number)
---   The maximum width, in characters, of auto-completion and user lists.
---   Set to `0` to autosize to fit longest item, which is the default.
+--   The maximum number of characters per row to show in autocompletion and user
+--   lists.
+--   The default value is `0`, which automatically sizes the list to fit the
+--   longest item.
 -- @field auto_c_separator (number)
---   The auto-completion list separator character byte.
---   The default is the space character.
+--   The character byte that separates autocompletion list items.
+--   The default value is `32` (' ').
 -- @field auto_c_type_separator (number)
---   The auto-completion list type-separator character byte.
---   The default is `63` ('?'). Autocompletion list items may display an image
---   as well as text. Each image is first registered with an integer type. Then
---   this integer is included in the text of the list separated by a '?' from
---   the text.
+--   The character byte that separates autocompletion 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
+--   image types to list items after type separator characters.
+--   The default value is 63 ('?').
 -- @field back_space_un_indents (bool)
---   Whether a backspace pressed when caret is within indentation unindents.
+--   Un-indent text when backspacing within indentation.
+--   The default value is `false`.
 -- @field buffered_draw (bool)
---   Whether drawing is buffered.
---   If drawing is buffered then each line of text is drawn into a bitmap buffer
---   before drawing it to the screen to avoid flicker. The default is for
---   drawing to be buffered. first or directly onto the screen.
+--   Buffer drawing to avoid flickering.
+--   Buffering draws each line of text into a bitmap buffer before drawing the
+--   bitmap to the screen.
+--   The default value is `true`.
 -- @field call_tip_back (number, Write-only)
---   The background color for the call tip in "0xBBGGRR" format.
+--   The background color, in "0xBBGGRR" format, for a call tip.
 -- @field call_tip_fore (number, Write-only)
---   The foreground color for the call tip in "0xBBGGRR" format.
+--   The foreground color, in "0xBBGGRR" format, for a call tip.
 -- @field call_tip_fore_hlt (number, Write-only)
---   The foreground color for the highlighted part of the call tip in "0xBBGGRR"
---   format.
+--   The foreground color, in "0xBBGGRR" format, for the highlighted part of a
+--   call tip.
 -- @field call_tip_position (boolean)
---   The position of calltip, above or below text.
---   By default the calltip is displayed below the text. Setting to `true` will
---   display it above the text.
+--   Display the call tip above or below the text.
+--   The default value is `false` to display the call tip below the text.
 -- @field call_tip_use_style (number)
---   Enable use of `_SCINTILLA.constants.STYLE_CALLTIP` and set call tip tab
---   size in pixels.
---   If the tab size is less than `1`, Tab characters are not treated specially.
+--   The size in pixels of tab characters in call tips.
+--   When non-zero, also enables the use of `_SCINTILLA.constants.STYLE_CALLTIP`
+--   instead of `_SCINTILLA.constants.STYLE_DEFAULT` for call tip styles.
+--   The default value is `0`, which does not treat tab characters specially.
 -- @field caret_fore (number)
---   The foreground color of the caret in "0xBBGGRR" format.
+--   The foreground color, in "0xBBGGRR" format, of the caret.
 -- @field caret_line_back (number)
---   The color of the background of the line containing the caret in "0xBBGGRR"
---   format.
+--   The background color, in "0xBBGGRR" format, of the line containing the
+--   caret.
 -- @field caret_line_back_alpha (number)
---   The background alpha of the caret line.
---   Alpha ranges from `0` (transparent) to `255` (opaque) or `256` for no
---   alpha.
+--   The background alpha value, ranging from `0` (transparent) to `255`
+--   (opaque), of the caret line.
+--   The default value is `256`, for no alpha.
 -- @field caret_line_visible (bool)
---   Whether the background of the line containing the caret is in a different
---   color.
+--   Color the background of the line containing the caret a different color.
+--   The default value is `false`.
 -- @field caret_period (number)
---   The time in milliseconds that the caret is on and off.
---   Setting the period to `0` stops the caret blinking. The default value is
---   500 milliseconds.
+--   The time in milliseconds between caret blinks.
+--   A value of `0` stops blinking.
+--   The default value is `500`.
 -- @field caret_sticky (number)
---   The caret preferred x position changing when the user types.
+--   The preferred horizontal position of the caret when moving between lines.
 --
 --   * `_SCINTILLA.constants.SC_CARETSTICKY_OFF` (0)
---     All text changes (and all caret position changes) will remember the
---     caret's new horizontal position when moving to different lines.
---     This is the default.
+--     Use the same position as on the previous line.
 --   * `_SCINTILLA.constants.SC_CARETSTICKY_ON` (1)
---     The only thing which will cause the editor to remember the horizontal
---     caret position is moving the caret with mouse or keyboard (left/right
---     arrow keys, home/end keys, etc).
+--     Use the last position the caret was moved to via the mouse, left/right
+--     arrow keys, home/end keys, etc. Typing text does not affect the position.
 --   * `_SCINTILLA.constants.SC_CARETSTICKY_WHITESPACE` (2)
---     The caret acts like sticky off except under one special case; when space
---     or tab characters are inserted. (Including pasting *only space/tabs* --
---     undo, redo, etc. do not exhibit this behavior.)
+--     Use the same position as on the previous line, but prior to any inserted
+--     indentation.
+--
+--   The default value is `0`.
 -- @field caret_style (number)
---   The style of the caret to be drawn.
+--   The style of caret to draw.
 --
 --   * `_SCINTILLA.constants.CARETSTYLE_INVISIBLE` (0)
---     Not draw the caret at all.
+--     No caret.
 --   * `_SCINTILLA.constants.CARETSTYLE_LINE` (1)
---     A line caret. This is the default value.
+--     A line caret.
 --   * `_SCINTILLA.constants.CARETSTYLE_BLOCK` (2)
 --     A block caret.
+--
+--   The default value is `1`.
 -- @field caret_width (number)
---   The width of the insert mode caret in pixels.
---   Can be `0`, `1`, `2` or `3` pixels. The default width is 1 pixel. This
---   setting only affects the width of the cursor when the cursor style is set
---   to line caret mode, it does not affect the width for a block caret.
+--   The pixel width of the caret in insert mode, either `0`, `1`, `2`, or `3`,
+--   and only applicable to line carets.
+--   The default value is `1`.
 -- @field char_at (table, Read-only)
---   Table of character bytes at positions in the document starting at zero.
+--   Table of character bytes at positions in the buffer starting from zero.
 -- @field code_page (number)
---   The code page used to interpret the bytes of the document as characters.
---   The `_SCINTILLA.constants.SC_CP_UTF8` value can be used to enter Unicode
---   mode.
+--   The code page used to interpret buffer bytes as characters.
+--
+--   + `0` None.
+--   + `932` Japanese Shift-JIS.
+--   + `936` Simplified Chinese GBK.
+--   + `949` Korean Unified Hangul Code.
+--   + `950` Traditional Chinese Big5.
+--   + `1361` Korean Johab.
+--   + `_SCINTILLA.constants.SC_CP_UTF8` (65001) UTF-8.
+--
+--   The default value is `0`.
 -- @field column (table, Read-only)
---   Table of column numbers, taking tab widths into account, for positions
---   starting from zero.
+--   Table of column numbers, taking tab widths into account, for positions in
+--   the buffer starting from zero.
 -- @field control_char_symbol (number)
---   The way control characters are displayed.
---   If less than `32`, keep the rounded rectangle as ASCII mnemonics.
---   Otherwise, use the given character byte. The default value is `0`.
+--   The byte value of the character displayed in place of control characters,
+--   characters whose byte values are less than 32. Values less than 32 dispay
+--   ASCII mnemonics instead.
+--   The default value is `0`.
 -- @field current_pos (number)
 --   The position of the caret.
---   When setting, the caret is not scrolled into view.
+--   When set, does not scroll the caret into view.
 -- @field cursor (number)
 --   The cursor type.
 --
 --   * `_SCINTILLA.constants.SC_CURSORNORMAL` (-1)
---     The normal cursor is displayed.
+--     The normal cursor.
 --   * `_SCINTILLA.constants.SC_CURSORWAIT` (4)
---     The wait cursor is displayed when the mouse is over the view.
--- @field direct_function (number, Read-only)
---   A pointer to a function that processes messages for this view.
--- @field direct_pointer (number, Read-only)
---   A pointer value to use as the first argument when calling the function
---   returned by direct_function.
--- @field dirty (bool)
---   Flag indicating whether or not the buffer has been modified since it was
---   last saved.
--- @field eol_mode (number)
---   The current end of line mode.
+--     The wait cursor.
 --
---   * `_SCINTILLA.constants.SC_EOL_CRLF` (0)
---     "CR+LF" ("\r\n").
---   * `_SCINTILLA.constants.SC_EOL_CR` (1)
---     "CR" ("\r").
---   * `_SCINTILLA.constants.SC_EOL_LF` (2)
---     "LF" ("\n").
+--   The default value is `-1`.
+-- @field dirty (bool)
+--   Whether or not the buffer has unsaved changes.
+--   Unlike [`buffer.modify`](#modify), this field is accessible from any
+--   buffer, not just the global one.
 -- @field edge_colour (number)
---   The color used in edge indication in "0xBBGGRR" format.
+--   The color, in "0xBBGGRR" format, used for the long line marker.
 -- @field edge_column (number)
---   The column number which text should be kept within.
+--   The column number to display the long line marker at.
 -- @field edge_mode (number)
---   The edge highlight mode.
+--   The long line edge mode.
 --
 --   * `_SCINTILLA.constants.EDGE_NONE` (0)
---     Long lines are not marked. This is the default state.
+--     Long lines are not marked.
 --   * `_SCINTILLA.constants.EDGE_LINE` (1)
---     A vertical line is drawn at the column number set by
---     `buffer.edge_column`.
+--     Draw a vertical line whose color is [`buffer.edge_colour`](#edge_colour)
+--     at column [`buffer.edge_column`](#edge_column).
 --   * `_SCINTILLA.constants.EDGE_BACKGROUND` (2)
---     The background color of characters after the column limit is changed to
---     the color set by `buffer.edge_colour`.
+--     Change the background color of characters after column
+--     [`buffer.edge_column`](#edge_column) to
+--     [`buffer.edge_colour`](#edge_colour).
 -- @field encoding (string or nil)
---   The encoding of the file on the hard disk.
---   It will be `nil` if the file is a binary file.
+--   The string encoding of the file on the hard drive or `nil` for binary
+--   files.
 -- @field encoding_bom (string)
---   The byte-order mark of the file encoding (if any).
+--   The byte-order mark, if any, of the file encoding.
 -- @field end_at_last_line (bool)
---   Whether the maximum scroll position has the last line at the bottom of the
---   view.
---   If `false`, allows scrolling one page below the last line. The default
---   value is `true`.
+--   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.
+-- @field eol_mode (number)
+--   The current end of line mode.
+--
+--   * `_SCINTILLA.constants.SC_EOL_CRLF` (0)
+--     "CR+LF" ("\r\n").
+--   * `_SCINTILLA.constants.SC_EOL_CR` (1)
+--     "CR" ("\r").
+--   * `_SCINTILLA.constants.SC_EOL_LF` (2)
+--     "LF" ("\n").
+--
+--   The default value is `0` on Windows platforms, `2` otherwise.
 -- @field extra_ascent (number)
---   The extra ascent, the maximum that any style extends above the baseline,
---   added to each line.
+--   The amount of pixel padding above line text.
+--   The default value is `0`.
 -- @field extra_descent (number)
---   The extra descent, the maximum that any style extends below the baseline,
---   added to each line.
+--   The amount of pixel padding below line text.
+--   The default is `0`.
 -- @field filename (string)
---   The absolute path to the file associated with this buffer.
---   It is encoded in UTF-8. Use [`string.iconv()`](string.html#iconv) for
---   charset conversions.
+--   The UTF-8-encoded absolute path to the file associated with the buffer.
+--   Use [`string.iconv()`][] and [`_G._CHARSET`][] for charset conversions.
+--
+--   [`string.iconv()`]: string.html#iconv
+--   [`_G._CHARSET`]: _G.html#_CHARSET
 -- @field first_visible_line (number)
---   The display line at the top of the display.
--- @field focus (bool)
---   The internal focus flag.
--- @field fold_expanded (bool)
---   Expanded state of a header line.
+--   The line number of the line at the top of the view, starting from zero.
+-- @field fold_expanded (table)
+--   Table of flags indicating whether or not folds are expanded for line
+--   numbers starting from zero.
+--   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)
---   The style options for folding.
---   Bits set in flags determine where folding lines are drawn:
+--   Bit-mask of options for drawing folding lines.
 --
 --   * `_SCINTILLA.constants.SC_FOLDFLAG_LINEBEFORE_EXPANDED` (2)
---     Draw above if expanded.
+--     Draw lines above expanded folds.
 --   * `_SCINTILLA.constants.SC_FOLDFLAG_LINEBEFORE_CONTRACTED` (4)
---     Draw above if not expanded.
+--     Draw lines above collapsed folds.
 --   * `_SCINTILLA.constants.SC_FOLDFLAG_LINEAFTER_EXPANDED` (8)
---     Draw below if expanded.
+--     Draw lines below expanded folds.
 --   * `_SCINTILLA.constants.SC_FOLDFLAG_LINEAFTER_CONTRACTED` (16)
---     Draw below if not expanded.
+--     Draw lines below collapsed folds.
+--
+--   The default value is `0`.
 -- @field fold_level (table)
---   Table of fold levels for lines starting from zero.
---   Fold levels encodes an integer level along with flags indicating whether
---   the line is a header and whether it is effectively white space.
+--   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
+--   following bits:
 --
 --   * `_SCINTILLA.constants.SC_FOLDLEVELBASE` (0x400)
---     Initial fold level.
+--     The initial fold level.
 --   * `_SCINTILLA.constants.SC_FOLDLEVELWHITEFLAG` (0x1000)
---     Indicates that the line is blank.
+--     The line is blank.
 --   * `_SCINTILLA.constants.SC_FOLDLEVELHEADERFLAG` (0x2000)
---     Indicates that the line is a header (fold point).
+--     The line is a header, or fold point.
 -- @field fold_parent (table, Read-only)
---   Table of parent line numbers for child lines starting from zero.
---   `-1` means no line was found.
--- @field font_quality (number) (Windows only)
---   The quality level for text.
---
---   * `_SCINTILLA.constants.SC_EFF_QUALITY_DEFAULt` (0).
---   * `_SCINTILLA.constants.SC_EFF_QUALITY_NON_ANTIALIASED` (1).
---   * `_SCINTILLA.constants.SC_EFF_QUALITY_ANTIALIASED` (2).
---   * `_SCINTILLA.constants.SC_EFF_QUALITY_LCD_OPTIMIZED` (3).
--- @field gap_position (number, Read-only)
---   A position which, to avoid performance costs, should not be within the
---   range of a call to `buffer:get_range_pointer()`.
+--   Table of parent line numbers (fold points) for child line numbers starting
+--   from zero.
+--   A line number of `-1` means no line was found.
 -- @field h_scroll_bar (bool)
---   Whether the horizontal scroll bar is visible.
---   Set to `false` to never see it and `true` to enable it again. The default
---   state is to display it when needed.
+--   Display the horizontal scroll bar.
+--   The default value is `true`.
 -- @field highlight_guide (number)
---   The highlighted indentation guide column.
---   Set to `0` to cancel this highlight.
+--   The indentation guide column number to highlight, or `0` to stop
+--   highlighting.
 -- @field hotspot_active_underline (bool)
---   Whether active hotspots are underlined.
+--   Underline active hotspots.
+--   The default value is `true`.
 -- @field hotspot_single_line (bool)
---   Whether hotspots are limited to single line so hotspots on two lines do not
---   merge.
+--   Limit hotspots to a single line.
+--   The default value is `true`.
 -- @field indent (number)
---   Ihe number of spaces used for one level of indentation.
---   For a width of `0`, the indent size is the same as the tab size.
+--   The number of spaces used for one level of indentation.
+--   The default value is `0`, which matches the tab size.
 -- @field indentation_guides (number)
---   Indentation guides appearance.
+--   The indentation guide drawing mode.
 --   Indentation guides are dotted vertical lines that appear within indentation
---   white space every indent size columns.
+--   whitespace at each level of indentation.
 --
 --   * `_SCINTILLA.constants.SC_IV_NONE` (0)
---     No indentation guides are shown.
+--     Guides are not drawn.
 --   * `_SCINTILLA.constants.SC_IV_REAL` (1)
---     Indentation guides are shown inside real indentation white space.
+--     Draw guides only within indentation whitespace.
 --   * `_SCINTILLA.constants.SC_IV_LOOKFORWARD` (2)
---     Indentation guides are shown beyond the actual indentation up to the
---     level of the next non-empty line.
---     If the previous non-empty line was a fold header then indentation guides
---     are shown for one more level of indent than that line. This setting is
---     good for Python.
+--     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
+--     fold header.
 --   * `_SCINTILLA.constants.SC_IV_LOOKBOTH` (3)
---     Indentation guides are shown beyond the actual indentation up to the
---     level of the next non-empty line or previous non-empty line whichever is
---     the greater.
---     This setting is good for most languages.
+--     Draw guides beyond the current line up to either the level of the
+--     previous or next non-empty line, whichever is greater.
+--
+--   The default value is `0`.
 -- @field indic_alpha (table)
---   Table of alpha transparency values ranging from `0` (transparent) to `255`
---   (opaque) or `256` (no alpha) for indicators from `0` to `31`.
---   Used for drawing the fill color of the `INDIC_ROUNDBOX` and
---   `INDIC_STRAIGHTBOX` rectangle.
+--   Table of fill color alpha values, ranging from `0` (transparent) to `255`
+--   (opaque), for indicator numbers from `0` to `31` whose styles are either
+--   `INDIC_ROUNDBOX`, `INDIC_STRAIGHTBOX`, or `INDIC_DOTBOX`.
+--   The default values are `256`, for no alpha.
 -- @field indic_fore (table)
---   Table of foreground colors in "0xBBGGRR" format for indicators from `0` to
---   `31`.
+--   Table of foreground colors, in "0xBBGGRR" format, for indicator numbers
+--   from `0` to `31`.
 -- @field indic_outline_alpha (table)
---   Table of alpha transparency values ranging from `0` (transparent) to `255`
---   (opaque) or `256` (no alpha) for indicators from `0` to `31`.
---   Used for drawing the outline color of the `INDIC_ROUNDBOX` and
---   `INDIC_STRAIGHTBOX` rectangle.
+--   Table of outline color alpha values, ranging from `0` (transparent) to
+--   `255` (opaque), for indicator numbers from `0` to `31` whose styles are
+--   either `INDIC_ROUNDBOX`, `INDIC_STRAIGHTBOX`, or `INDIC_DOTBOX`.
+--   The default values are `256`, for no alpha.
 -- @field indic_style (table)
---   Table of styles for indicators from `0` to `31`.
+--   Table of styles for indicator numbers from `0` to `31`.
 --
 --   * `_SCINTILLA.constants.INDIC_PLAIN` (0)
---     Underlined with a single, straight line.
+--     An underline.
 --   * `_SCINTILLA.constants.INDIC_SQUIGGLE` (1)
---     A squiggly underline. Requires 3 pixels of descender space.
+--     A squiggly underline 3 pixels in height.
 --   * `_SCINTILLA.constants.INDIC_TT` (2)
---     A line of small T shapes.
+--     A line of small 'T' shapes.
 --   * `_SCINTILLA.constants.INDIC_DIAGONAL` (3)
 --     Diagonal hatching.
 --   * `_SCINTILLA.constants.INDIC_STRIKE` (4)
 --     Strike out.
 --   * `_SCINTILLA.constants.INDIC_HIDDEN` (5)
---     An indicator with no visual effect.
+--     Invisible.
 --   * `_SCINTILLA.constants.INDIC_BOX` (6)
 --     A rectangle around the text.
 --   * `_SCINTILLA.constants.INDIC_ROUNDBOX` (7)
---     A rectangle with rounded corners around the text using translucent
---     drawing with the interior usually more transparent than the border. Use
---     `buffer.indic_alpha` and `buffer.indic_outline_alpha` to control the
---     alpha transparency values. The default alpha values are `30` for fill
---     color and `50` for outline color.
+--     A translucent rectangle with rounded corners around the text. Use
+--     [`buffer.indic_alpha`](#indic_alpha) and
+--     [`buffer.indic_outline_alpha`](#indic_outline_alpha) to set the fill and
+--     outline transparency, respectively. Their default values are `30` and
+--     `50`.
 --   * `_SCINTILLA.constants.INDIC_STRAIGHTBOX` (8)
---     A rectangle around the text using translucent drawing with the interior
---     usually more transparent than the border.
---     You can use `buffer.indic_alpha` and `buffer.indic_outline_alpha` to
---     control the alpha transparency values. The default alpha values are `30`
---     for fill color and `50` for outline color.
+--     Similar to `INDIC_ROUNDBOX` but with sharp corners.
 --   * `_SCINTILLA.constants.INDIC_DASH` (9)
 --     A dashed underline.
 --   * `_SCINTILLA.constants.INDIC_DOTS` (10)
 --     A dotted underline.
 --   * `_SCINTILLA.constants.INDIC_SQUIGGLELOW` (11)
---     Similar to `INDIC_SQUIGGLE` but only using 2 vertical pixels so will fit
---     under small fonts.
+--     A squiggly underline 2 pixels in height.
 --   * `_SCINTILLA.constants.INDIC_DOTBOX` (12)
---     A dotted rectangle around the text using translucent drawing.
---     Translucency alternates between the alpha and outline alpha settings with
---     the top-left pixel using the alpha setting. `buffer.indic_alpha` and
---     `buffer.indic_outline_alpha` control the alpha transparency values.
---     The default values are `30` for alpha and `50` for outline alpha. To
---     avoid excessive memory allocation the maximum width of a dotted box is
---     4000 pixels.
+--     Similar to `INDIC_STRAIGHTBOX` but with a dotted outline.
+--     Translucency alternates between [`buffer.indic_alpha`](#indic_alpha) and
+--     [`buffer.indic_outline_alpha`](#indic_outline_alpha) starting with the
+--     top-left pixel.
 --   * `_SCINTILLA.constants.INDIC_SQUIGGLEPIXMAP` (13)
---     A version of `INDIC_SQUIGGLE` that draws using a pixmap instead of as a
---     series of line segments for performance. Measured to be between 3 and 6
---     times faster than `INDIC_SQUIGGLE` on GTK+. Apperance will not be as good
---     as `INDIC_SQUIGGLE` on OSX in HiDPI mode.
---   * Use `_SCINTILLA.next_indic_number()` for custom indicators.
+--     Identical to `INDIC_SQUIGGLE` but draws faster by using a pixmap instead
+--     of multiple line segments.
+--
+--   Use [`_SCINTILLA.next_indic_number()`][] for custom indicators.
+--
+--   [`_SCINTILLA.next_indic_number()`]: _SCINTILLA.html#next_indic_number
 -- @field indic_under (table)
---   Table of booleans for drawing under text or over (default) for indicators
---   from `0` to `31`.
+--   Table of flags indicating whether to draw indicators over text or under it
+--   for indicator numbers from `0` to `31`.
+--   For values to be `true`, [`buffer.two_phase_draw`](#two_phase_draw) must be
+--   `true`.
+--   The default values are `false` for drawing indicators over text.
 -- @field indicator_current (number)
---   The indicator in the range of `0` to `31` used for
---   `buffer:indicator_fill_range()` and `buffer:indicator_clear_range()`.
+--   The indicator number in the range of `0` to `31` used by
+--   [`buffer:indicator_fill_range()`](#indicator_fill_range) and
+--   [`buffer:indicator_clear_range()`](#indicator_clear_range).
 -- @field indicator_value (number)
---   The indicator value used for `buffer:indicator_fill_range()`.
---   Currently all values are drawn the same.
--- @field keys_unicode (bool)
---   Interpret keyboard input as Unicode.
+--   The indicator value used for
+--   [`buffer:indicator_fill_range()`](#indicator_fill_range).
+--   Currently, all values are drawn the same, but it may be possible to draw
+--   different values in different styles in the future.
 -- @field layout_cache (number)
---   The degree of caching of layout information.
+--   The layout cache mode.
 --
 --   * `_SCINTILLA.constants.SC_CACHE_NONE` (0)
 --     No lines are cached.
 --   * `_SCINTILLA.constants.SC_CACHE_CARET` (1)
---     The line containing the text caret.
---     This is the default.
+--     Cache the line containing the caret.
 --   * `_SCINTILLA.constants.SC_CACHE_PAGE` (2)
---     Visible lines plus the line containing the caret.
+--     Cache visible lines.
 --   * `_SCINTILLA.constants.SC_CACHE_DOCUMENT` (3)
---     All lines in the document.
+--     Cache all lines in the buffer.
+--
+--   The default value is `1`.
 -- @field length (number, Read-only)
---   The number of bytes in the document.
+--   The number of bytes in the buffer.
 -- @field lexer (number)
---   The lexing language of the document.
+--   The numeric ID of the Scintilla lexer used by the buffer.
 -- @field lexer_language (string)
---   The name of the lexer.
+--   The name of the Scintilla lexer used by the buffer.
+--   You probably want to use [`buffer:get_lexer()`](#get_lexer) instead.
 -- @field line_count (number, Read-only)
---   The number of lines in the document.
+--   The number of lines in the buffer.
 --   There is always at least one.
 -- @field line_end_position (table, Read-only)
---   Table of positions after the last visible characters on a line for lines
---   starting from zero.
+--   Table of positions at the ends of lines, but before any end of line
+--   characters, for line numbers starting from zero.
 -- @field line_indent_position (table, Read-only)
---   Table of positions before the first non indentation character on a line for
---   lines starting from zero.
+--   Table of positions at the ends of line indentation for line numbers
+--   starting from zero.
 -- @field line_indentation (table)
---   Table of line indentation amounts for lines starting from zero.
---   The indentation is measured in character columns, which correspond to the
---   width of space characters.
+--   Table of line indentation amounts, measured in character columns, for line
+--   numbers starting from zero.
 -- @field line_state (table)
---   Table of extra styling information for lines starting from zero.
---   As well as the 8 bits of lexical state stored for each character there is
---   also an integer stored for each line. This can be used for longer lived
---   parse states.
--- @field line_visible (bool, Read-only)
---   Is a line visible?
+--   Table of integer line states for line numbers starting from zero.
+--   Line states are used for storing longer lived parse states per line. They
+--   are available in addition to the 8 bits of styling information per
+--   character.
+-- @field line_visible (table, Read-only)
+--   Table of flags indicating whether or not lines are visible for line numbers
+--   starting from zero.
 -- @field lines_on_screen (number, Read-only)
---   The number of lines completely visible.
--- @field lines_visible (bool, Read-only)
---   Are all lines visible?
+--   The number of completely visible lines in the view.
+--   It is possible to have a partial line visible at the bottom of the view.
 -- @field main_selection (number)
---   The main selection.
---   The main selection may be displayed in different colors or with a
---   differently styled caret. Only an already existing selection can be made
---   main.
+--   The main, or most recent, selection.
+--   Only an existing selection can be made main.
 -- @field margin_cursor_n (table)
---   Table of cursors shown for margins from zero to four.
---   A reversed arrow cursor is normally shown over all margins.
+--   Table of cursors shown for margin numbers from zero to four.
 --
---   * `_SCINTILLA.constants.SC_CURSORARROW`
---     Normal arrow.
---   * `_SCINTILLA.constants.SC_CURSORREVERSEARROW`
---     Reversed arrow.
+--   * `_SCINTILLA.constants.SC_CURSORARROW` (2)
+--     Normal arrow cursor.
+--   * `_SCINTILLA.constants.SC_CURSORREVERSEARROW` (7)
+--     Reversed arrow cursor.
+--
+--   The default values are `7`.
 -- @field margin_left (number)
---   The size in pixels of the left margin.
---   The default is to one pixel.
+--   The size in pixels of the left margin of the buffer text.
+--   The default value is `1`.
 -- @field margin_mask_n (table)
---   Table of marker masks for margins from zero to four.
---   A mask determines which markers are displayed in a margin.
+--   Table of marker bit-masks for showing margin markers for margin numbers
+--   from zero to four.
+--   The default values are `0`, `0x1FFFFFF`, `0`, `0`, and `0`, for a line
+--   margin and logical marker margin.
 -- @field margin_options (number)
---   A bit mask of margin options.
+--   A bit-mask of margin option settings.
 --
 --   * `_SCINTILLA.constants.SC_MARGINOPTION_NONE` (0)
---     None (default).
+--     None.
 --   * `_SCINTILLA.constants.SC_MARGINOPTION_SUBLINESELECT` (1)
---     Controls how wrapped lines are selected when clicking on margin in front
---     of them.
---     If set, only sub line of wrapped line is selected, otherwise whole
---     wrapped line is selected.
+--     Select only the sub-line of the wrapped line on margin click.
+--
+--   The default value is `0`.
 -- @field margin_right (number)
---   The size in pixels of the right margin.
---   The default is to one pixel.
+--   The size in pixels of the right margin of the buffer text.
+--   The default value is `1`.
 -- @field margin_sensitive_n (table)
---   Table of mouse click sensitivity booleans for margins from zero to four.
---   A click in a sensitive margin emits a `MARGIN_CLICK` event. By default, all
---   margins are insensitive.
+--   Table of flags indicating whether or not mouse clicks in margins emit
+--   `MARGIN_CLICK` events for margin numbers from zero to four.
+--   The default values are `false`.
 -- @field margin_style (table)
---   Table of style numbers for text margin lines starting from zero.
+--   Table of style numbers for text margin line numbers starting from zero.
 --   Only some style attributes are active in text margins: font,
 --   size/size_fractional, bold/weight, italics, fore, back, and character_set.
 -- @field margin_style_offset (number)
---   The start of the range of style numbers used for margin text.
+--   The beginning of the range of style numbers used for margin text.
 --   Margin styles may be completely separated from standard text styles by
 --   setting a style offset. For example, setting this to `256` would allow the
 --   margin styles to be numbered from `256` upto `511` so they do not overlap
---   styles set by lexers. Each style number set with `buffer.margin_style` has
+--   styles set by lexers. Each style number set with `margin_style` has
 --   the offset added before looking up the style.
 -- @field margin_text (table)
---   Table of text in the text margin for lines starting from zero.
+--   Table of text in the text margin for line numbers starting from zero.
 -- @field margin_type_n (table)
---   Table of margin types for margins from zero to four.
+--   Table of margin types for margin numbers from zero to four.
 --
 --   * `_SCINTILLA.constants.SC_MARGIN_SYMBOL` (0)
 --     A symbol margin.
 --   * `_SCINTILLA.constants.SC_MARGIN_NUMBER` (1)
 --     A line number margin.
 --   * `_SCINTILLA.constants.SC_MARGIN_BACK` (2)
---     A symbol margin that sets its background color to match the default
---     text background color.
+--     A symbol margin whose background color matches the default text
+--     background color.
 --   * `_SCINTILLA.constants.SC_MARGIN_FORE` (3)
---     A symbol margin that sets its background color to match the default
---     text foreground color.
+--     A symbol margin whose foreground color matches the default text
+--     foreground color.
 --   * `_SCINTILLA.constants.SC_MARGIN_TEXT` (4)
 --     A text margin.
 --   * `_SCINTILLA.constants.SC_MARGIN_RTEXT` (5)
---     A right justified text margin.
+--     A right-justified text margin.
+--
+--   The default values are `true`, `false`, `false`, `false`, and `false`, for
+--   a line number margin and symbol margins.
 -- @field margin_width_n (table)
---   Table of margin widths expressed in pixes for margins from zero to four.
+--   Table of margin widths in pixels for margin numbers from zero to four.
 -- @field marker_alpha (table, Write-only)
---   Table of alpha values used for markers that are drawn in the text area, not
---   the margin.
---   Markers are numbers in the range of `0` to `31`. Alpha values are between
---   `0` (transparent) and `255` (opaque), or `256` for no alpha.
+--   Table of alpha values, ranging from `0` (transparent) to `255` (opaque),
+--   used for markers drawn in the text area, not the margin, for markers
+--   numbers from `0` to `31`.
+--   The default values are `256`, for no alpha.
 -- @field marker_back (table, Write-only)
---   Table of the background colors used for particular marker numbers.
---   Marker numbers are in the range of `0` to `31`. Colors are in "0xBBGGRR"
---   format.
+--   Table of background colors, in "0xBBGGRR" format, used for marker numbers
+--   from `0` to `31`.
 -- @field marker_back_selected (table, Write-only)
---   Table of the background colors used for particular marker numbers when
---   their folding blocks are selected.
---   Marker numbers are in the range of `0` to `31`. Colors are in "0xBBGGRR"
---   format. The default color is `0x0000FF`.
+--   Table of background colors, in "0xBBGGRR" format, used for markers whose
+--   folding blocks are selected for marker numbers from `0` to `31`.
+--   The default values are `0x0000FF`.
 -- @field marker_fore (table, Write-only)
---   Table of the foreground colors used for particular marker numbers.
---   Marker numbers are in the range of `0` to `31`. Colors are in "0xBBGGRR"
---   format.
+--   Table of foreground colors, in "0xBBGGRR" format, used for marker numbers
+--   from `0` to `31`.
 -- @field max_line_state (number, Read-only)
---   The last line number that has line state.
+--   The last line number with a non-zero line state.
 -- @field modify (bool)
---   Whether the document is different from when it was last saved.
--- @field mouse_down_captures (bool)
---   Whether the mouse is captured when its button is pressed.
+--   Whether or not the buffer has unsaved changes.
+--   Unlike [`buffer.dirty`](#dirty), this field is accessible only from the
+--   global buffer.
 -- @field mouse_dwell_time (number)
---   The time the mouse must sit still to generate a mouse dwell event.
---   If set to `_SCINTILLA.constants.SC_TIME_FOREVER`, the default, no dwell
---   events are generated.
--- @field multi_paste (bool)
---   The effect of pasting when there are multiple selections.
+--   The number of milliseconds the mouse must idle in order to generate a
+--   `DWELL_START` event, or `_SCINTILLA.constants.SC_TIME_FOREVER` to never
+--   generate one.
+-- @field multi_paste (number)
+--   The multiple selection paste mode.
 --
 --   * `_SCINTILLA.constants.SC_MULTIPASTE_ONCE` (0)
---     Pasted text can go into just the main selection (default).
+--     Paste into only the main selection.
 --   * `_SCINTILLA.constants.SC_MULTIPASTE_EACH` (1)
---     Pasted text can go into each selection.
+--     Paste into all selections.
+--
+--   The default value is `0`.
 -- @field multiple_selection (bool)
---   Whether multiple selections can be made.
---   When multiple selection is disabled, it is not possible to select multiple
---   ranges by holding down the Ctrl key while dragging with the mouse.
+--   Enable multiple selection.
+--   The default value is `false`.
 -- @field overtype (bool)
---   Overtype mode.
+--   Enable overtype mode, where typed characters overwrite existing ones.
+--   The default value is `false`.
 -- @field position_cache (number)
 --   The number of entries in the position cache.
 --   The position cache stores position information for short runs of text so
 --   that their layout can be determined more quickly if the run recurs.
+--   The default value is `1024`.
 -- @field print_colour_mode (number)
 --   The print color mode.
 --
 --   * `_SCINTILLA.constants.SC_PRINT_NORMAL` (0)
---     Print using the current screen colors.
---     This is the default.
+--     Print with the current set of colors.
 --   * `_SCINTILLA.constants.SC_PRINT_INVERTLIGHT` (1)
---     If you use a dark screen background this saves ink by inverting the light
---     value of all colors and printing on a white background.
+--     Print on a white background with the light values of the current color
+--     set.
+--     This mode is good for a dark background color.
 --   * `_SCINTILLA.constants.SC_PRINT_BLACKONWHITE` (2)
---     Print all text as black on a white background.
+--     Print black text on a white background.
 --   * `_SCINTILLA.constants.SC_PRINT_COLOURONWHITE` (3)
---     Everything prints in its own color on a white background.
+--     Print on a white background with the current color set.
 --   * `_SCINTILLA.constants.SC_PRINT_COLOURONWHITEDEFAULTBG` (4)
---     Everything prints in its own color on a white background except that line
---     numbers use their own background color.
+--     Print on a white background with the current color set except for line
+--     numbers which use their own background color.
 -- @field print_magnification (number)
---   The print magnification added to the point size of each style for printing.
+--   The number of points to add to the size of each font when printing.
+--   Negative values are allowed.
+--   The default value is `0`.
 -- @field print_wrap_mode (number)
---   Printing line wrap mode.
+--   The print line wrap mode.
 --
 --   * `_SCINTILLA.constants.SC_WRAP_NONE` (0)
---     Each line of text generates one line of output and the line is truncated
---     if it is too long to fit into the print area.
+--     Truncate long lines.
 --   * `_SCINTILLA.constants.SC_WRAP_WORD` (1)
---     Wraps printed output so that all characters fit into the print rectangle.
---     Tries to wrap only between words as indicated by white space or style
---     changes although if a word is longer than a line, it will be wrapped
---     before the line end. This is the default.
---   * `_SCINTILLA.constants.SC_WRAP_CHAR` (2).
+--     Wrap long lines at word boundaries if possible.
+--   * `_SCINTILLA.constants.SC_WRAP_CHAR` (2)
+--     Wrap long lines at character boundaries.
 -- @field property (table)
---   Table of keyword:value string pairs used by a lexer for some optional
---   features.
--- @field property_expanded (table)
---   Table of keyword:value string pairs used by a lexer for some optional
---   features with `$()` variable replacement on returned string.
+--   Map of key-value string pairs used by lexers.
+-- @field property_expanded (table, Read-only)
+--   Map of key-value string pairs used by lexers with `$()` variable
+--   replacement performed in values.
 -- @field property_int (table, Read-only)
---   Interprets `buffer.property[keyword]` as an integer if found or returns
---   `0`.
+--   Map of key-value pairs used by lexers with values interpreted as numbers,
+--   or `0` if not found.
 -- @field punctuation_chars (string)
---   The set of characters making up punctuation characters.
---   Use after setting `buffer.word_chars`.
+--   The set of characters considered to be punctuation characters.
+--   Set this only after setting [`buffer.word_chars`](#word_chars).
+--   The default value is a string containing all characters not considered to
+--   be whitespace or word characters.
 -- @field read_only (bool)
---   Read-only mode.
+--   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.
 -- @field rectangular_selection_anchor_virtual_space (number)
@@ -611,161 +624,198 @@
 -- @field rectangular_selection_caret_virtual_space (number)
 --   The amount of virtual space for the caret of the rectangular selection.
 -- @field rectangular_selection_modifier (number)
---   The modifier key used to indicate that a rectangular selection should be
---   created when combined with a mouse drag.
+--   The modifier key used in combination with a mouse drag to create a
+--   rectangular selection.
 --
 --   * `_SCINTILLA.constants.SCMOD_CTRL` (2)
---     Control key (default).
+--     The "Control" modifier key.
 --   * `_SCINTILLA.constants.SCMOD_ALT` (4)
---     Alt key.
+--     The "Alt" modifier key.
 --   * `_SCINTILLA.constants.SCMOD_SUPER` (8)
---     Left Windows key on a Windows keyboard or the Command key on a Mac.
+--     The "Super" modifier key, usually defined as the left "Windows" or
+--     "Command" key.
+--
+--   The default value is `2`.
 -- @field rgba_image_height (number)
---   The height for future RGBA image data.
+--   The height for an RGBA image to be defined using
+--   [`buffer:marker_define_rgba_image()`](#marker_define_rgba_image).
 -- @field rgba_image_scale (number)
---   The scale factor in percent for future RGBA image data.
+--   The scale factor in percent for an RGBA image to be defined using
+--   [`buffer:marker_define_rgba_image()`](#marker_define_rgba_image).
 --   This is useful on OSX with a retina display where each display unit is 2
 --   pixels: use a factor of `200` so that each image pixel is dsplayed using a
 --   screen pixel. The default scale, `100`, will stretch each image pixel to
 --   cover 4 screen pixels on a retina display.
 -- @field rgba_image_width (number)
---   The width for future RGBA image data.
+--   The width for an RGBA image to be defined using
+--   [`buffer:marker_define_rgba_image()`](#marker_define_rgba_image).
 -- @field scroll_width (number)
---   The document width assumed for scrolling.
---   For performance, the view does not measure the display width of the
---   document to determine the properties of the horizontal scroll bar. Instead,
---   an assumed width is used. The default value is `2000`. To ensure the width
---   of the currently visible lines can be scrolled use
---   `buffer.scroll_width_tracking`.
+--   The assumed document width for horizontal scrolling purposes.
+--   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
+--   can be scrolled use
+--   [`buffer.scroll_width_tracking`](#scroll_width_tracking).
+--   The default value is `2000`.
 -- @field scroll_width_tracking (bool)
---   Whether the maximum width line displayed is used to set scroll width.
+--   Set the scroll width to the maximum width of a displayed line beyond
+--   [`buffer.scroll_width`](#scroll_width).
+--   The default value is `false`.
 -- @field search_flags (number)
---   The search flags used by `buffer:search_in_target()`.
+--   The bit-mask of search flags used by
+--   [`buffer:search_in_target()`](#search_in_target).
 --
 --   * `_SCINTILLA.constants.SCFIND_WHOLEWORD` (2)
---     A match only occurs with text that matches the case of the search string.
+--     Match text surrounded by non-word characters.
 --   * `_SCINTILLA.constants.SCFIND_MATCHCASE` (4)
---     A match only occurs if the characters before and after are not word
---     characters.
+--     Match text case sensitively.
 --   * `_SCINTILLA.constants.SCFIND_WORDSTART` (0x00100000)
---     A match only occurs if the character before is not a word character.
+--     Match text when the previous character is a non-word character.
 --   * `_SCINTILLA.constants.SCFIND_REGEXP` (0x00200000)
---     The search string should be interpreted as a regular expression.
+--     Interpret the search string as a regular expression.
 --   * `_SCINTILLA.constants.SCFIND_POSIX` (0x00400000)
---     Treat regular expression in a more POSIX compatible manner by
---     interpreting bare '(' and ')' for tagged sections rather than "\\(" and
---     "\\)".
+--     Interpret '(' and ')' as tags instead of "\\(" and "\\)" in a regular
+--     expression.
+--
+--   The default value is `0`.
 -- @field sel_alpha (number)
---   The alpha of the selection, between `0` (transparent) and `255` (opaque),
---   or `256` for no alpha.
+--   The alpha value, ranging from `0` (transparent) to `255` (opaque), of the
+--   selection.
+--   The default value is `256`, for no alpha.
 -- @field sel_eol_filled (bool)
---   The selection end of line fill.
---   The selection can be drawn up to the right hand border by setting this
---   property.
+--   Extend the selection to the right margin of the view.
+--   The default value is `false`.
 -- @field selection_empty (bool, Read-only)
---   Is every selected range empty?
+--   Whether or not no text is selected.
 -- @field selection_end (number)
---   The position that ends the selection - this becomes the current position.
---   This does not make the caret visible.
+--   The position of the end of the selected text.
+--   When set, becomes the current position, but is not scrolled into view.
 -- @field selection_is_rectangle (bool, Read-only)
---   Is the selection rectangular?
---   The alternative is the more common stream selection.
+--   Whether or not the selection is a rectangular selection.
 -- @field selection_mode (number)
---   The mode of the current selection.
+--   The selection mode.
 --
 --   * `_SCINTILLA.constants.SC_SEL_STREAM` (0)
---     Stream.
+--     Character selection.
 --   * `_SCINTILLA.constants.SC_SEL_RECTANGLE` (1)
---     Rectangle.
+--     Rectangular selection.
 --   * `_SCINTILLA.constants.SC_SEL_LINES` (2)
---     Lines.
+--     Line selection.
 --   * `_SCINTILLA.constants.SC_SEL_THIN` (3)
---     Thin rectangular.
+--     Thin rectangular selection. This is the mode after a rectangular
+--     selection has been typed into and ensures that no characters are
+--     selected.
+--
+--   When set, caret movement alters the selected text until this field is set
+--   again to the same value or [`buffer:cancel()`](#cancel) is called.
 -- @field selection_n_anchor (table)
---   Table of anchor positions for existing selections starting from zero, the
+--   Table of anchor positions for existing selections numbered from zero, the
 --   main selection.
 -- @field selection_n_anchor_virtual_space (table)
 --   Table of the amount of virtual space for anchors for existing selections
---   starting from zero, the main selection.
+--   numbered from zero, the main selection.
 -- @field selection_n_caret (table)
---   Table of caret positions for existing selections starting from zero, the
+--   Table of caret positions for existing selections numbered from zero, the
 --   main selection.
 -- @field selection_n_caret_virtual_space (table)
 --   Table of the amount of virtual space for carets for existing selections
---   starting from zero, the main selection.
+--   numbered from zero, the main selection.
 -- @field selection_n_end (table)
---   Table of positions that end selections for existing selections starting
---   from zero, the main selection.
+--   Table of positions at the end of existing selections numbered from zero,
+--   the main selection.
 -- @field selection_n_start (table)
---   Table of positions that start selections for existing selections starting
---   from zero, the main selection.
+--   Table of positions at the beginning of existing selections numbered from
+--   zero, the main selection.
 -- @field selection_start (number)
---   The position that starts the selection - this becomes the anchor.
---   This does not make the caret visible.
+--   The position of the beginning of the selected text.
+--   When set, becomes the anchor, but is not scrolled into view.
 -- @field selections (number, Read-only)
---   The number of selections currently active.
--- @field status (number)
---   The error status.
---
---   * `_SCINTILLA.constants.SC_STATUS_OK` (0)
---     No failures.
---   * `_SCINTILLA.constants.SC_STATUS_FAILURE` (1)
---     Generic failure.
---   * `_SCINTILLA.constants.SC_STATUS_BADALLOC` (2)
---     Memory is exhausted.
+--   The number of active selections.
 -- @field style_at (table, Read-only)
---   Table of style bytes at positions in the document starting at zero.
+--   Table of style bytes at positions in the buffer starting from zero.
 -- @field style_back (table)
---   Table of background colors in "0xBBGGRR" format for styles from `0` to
---   `255`.
+--   Table of background colors, in "0xBBGGRR" format, for style numbers from
+--   `0` to `255`.
 -- @field style_bits (number)
---   The number of bits in style bytes used to hold the lexical state.
+--   The number of bits in an 8-bit style byte to use for styling.
+--   The number of styling bits required by the current lexer is
+--   [`buffer.style_bits_needed`](#style_bits_needed).
+--   The default value is `5`.
 -- @field style_bits_needed (number, Read-only)
---   The number of bits the current lexer needs for styling.
+--   The number of styling bits required by the current lexer.
 -- @field style_bold (table)
---   Table of booleans for bold styles from `0` to `255`.
+--   Table of flags indicating whether or not text within styles has a bold font
+--   face for style numbers from `0` to `255`.
+--   The default values are `false`.
 -- @field style_case (table)
---   Table of cases for styles from `0` to `255`.
+--   Table of letter case modes for text within styles for style numbers from
+--   `0` to `255`.
 --
 --   * `_SCINTILLA.constants.SC_CASE_MIXED` (0)
---     Normal, mixed case.
+--     Display text in mixed case.
 --   * `_SCINTILLA.constants.SC_CASE_UPPER` (1)
---     Upper case.
+--     Display text in upper case.
 --   * `_SCINTILLA.constants.SC_CASE_LOWER` (2)
---     Lower case.
+--     Display text in lower case.
+--
+--   The default values are `0`.
 -- @field style_changeable (table)
---   Table of booleans for changeable styles from `0` to `255`.
---   The default setting is `true`.
+--   Table of flags indicating whether or not text within styles is changeable
+--   for style numbers from `0` to `255`.
+--   The default values are `true`.
+--   Currently, read-only styles do not allow the caret into the range of text,
+--   but ranges containing read-only text are deletable.
 -- @field style_character_set (table)
---   Table of character sets for styles from `0` to `255`.
+--   Table of character sets for style numbers from `0` to `255`.
+--
+--   * `_SCINTILLA.constants.SC_CHARSET_ANSI` (0)
+--   * `_SCINTILLA.constants.SC_CHARSET_DEFAULT` (1)
+--   * `_SCINTILLA.constants.SC_CHARSET_CYRILLIC` (1251)
+--   * `_SCINTILLA.constants.SC_CHARSET_EASTEUROPE` (238)
+--   * `_SCINTILLA.constants.SC_CHARSET_GB2312` (134)
+--   * `_SCINTILLA.constants.SC_CHARSET_HANGUL` (129)
+--   * `_SCINTILLA.constants.SC_CHARSET_RUSSIAN` (204)
+--   * `_SCINTILLA.constants.SC_CHARSET_SHIFTJIS` (128)
+--   * `_SCINTILLA.constants.SC_CHARSET_8859_15` (1000)
+--
+--   The default values are `1`.
 -- @field style_eol_filled (table)
---   Table of booleans for end of line filled styles from `0` to `255`.
+--   Table of flags indicating whether or not to extend the background colors of
+--   styles whose characters occur last on lines all the way to the right margin
+--   of the view for style numbers from `0` to `255`.
+--   The default values are `false`.
 -- @field style_font (table)
---   Table of font faces for styles from `0` to `255`.
+--   Table of font faces for style numbers from `0` to `255`.
 -- @field style_fore (table)
---   Table of foreground colors in "0xBBGGRR" format for styles from `0` to
---   `255`.
+--   Table of foreground colors, in "0xBBGGRR" format, for style numbers from
+--   `0` to `255`.
 -- @field style_hot_spot (table)
---   Table of boolean hotspot styles from `0` to `255`.
+--   Table of flags indicating whether or not text within styles is clickable
+--   for style numbers from `0` to `255`.
+--   The default values are `false`.
 -- @field style_italic (table)
---   Table of booleans for italic styles from `0` to `255`.
+--   Table of flags indicating whether or not text within styles has an italic
+--   font face for style numbers from `0` to `255`.
+--   The default values are `false`.
 -- @field style_size (table)
---   Table of font sizes for styles from `0` to `255`.
---   Font size is a whole number of points.
+--   Table of font sizes, expressed in whole number points, for style numbers
+--   from `0` to `255`.
 -- @field style_size_fractional (table)
---   Table of sizes of characters for styles from `0` to `255`.
---   Size is in hundreths of a point and multiplied by 100 internally. For
---   example, a text size of 9.4 points is set with 940.
+--   Table of character sizes, expressed in hundredths of a point, for style
+--   numbers from `0` to `255`.
+--   For example, a text size of 9.4 points is set using `940`.
 -- @field style_underline (table)
---   Table of booleans for underlined styles from `0` to `255`.
+--   Table of flags indicating whether or not text within styles has an
+--   underlined font face for style numbers from `0` to `255`.
+--   The default values are `false`.
 -- @field style_visible (table)
---   Table of booleans for visible styles from `0` to `255`.
+--   Table of flags indicating whether or not text within styles is visible for
+--   style numbers from `0` to `255`.
+--   The default values are `true`.
 -- @field style_weight (table)
---   Table of character weights for styles from `0` to `255`.
---   The weight or boldness of a font can be set with a number between 1 and 999
---   with 1 being very light and 999 very heavy. While any value can be used,
---   fonts often only support between 2 and 4 weights with three weights being
---   common enough to use symbolic names:
+--   Table of character weights ranging from `1` (very light) to `999` (very
+--   heavy) for text within styles for style numbers from `0` to `255`.
+--   However, most fonts only support a small number of weights:
 --
 --   * `_SCINTILLA.constants.SC_WEIGHT_NORMAL` (400)
 --     Normal.
@@ -773,422 +823,444 @@
 --     Semi-bold.
 --   * `_SCINTILLA.constants.SC_WEIGHT_BOLD` (700)
 --     Bold.
+--
+--   The default values are `400`.
 -- @field tab_indents (bool)
---   Whether a tab pressed when caret is within indentation indents.
+--   Tabbing indents within indentation.
+--   The default value is `false`.
 -- @field tab_width (number)
---   The visible size of a tab as a multiple of the width of a space character.
---   The default tab width is 8 characters.
+--   The number of space characters represented by a tab character.
+--   The default value is `8`.
 -- @field tag (table)
---   Table of values of tags from a regular expression search.
+--   List of tag match values from a regular expression search.
 -- @field target_end (number)
---   The position that ends the target which is used for updating the document
---   without affecting the scroll position.
---   The target is also set by a successful `buffer:search_in_target()`.
+--   The position of the end of the target range.
+--   This is also set by a successful
+--   [`buffer:search_in_target()`](#search_in_target).
 -- @field target_start (number)
---   The position that starts the target which is used for updating the document
---   without affecting the scroll position.
---   The target is also set by a successful `buffer:search_in_target()`.
+--   The position of the beginning of the target range.
+--   This is also set by a successful
+--   [`buffer:search_in_target()`](#search_in_target).
 -- @field text_length (number, Read-only)
---   The number of characters in the document.
+--   The number of characters in the buffer.
 -- @field two_phase_draw (bool)
---   Two phase drawing mode.
---   When `true`, drawing is performed in two phases, first the background and
---   then the foreground. This avoids chopping off characters that overlap the
---   next run. The default is for drawing to be two phase.
+--   Draw in two phases: first the background and then the foreground.
+--   The default is `true`.
 -- @field undo_collection (bool)
---   Whether to collect undo information.
---   When stopping collection, use `buffer:empty_undo_buffer()` to avoid the
---   undo buffer being unsynchronized with the data in the buffer.
+--   Collect undo information.
+--   When setting to `false`, call
+--   [`buffer:empty_undo_buffer()`](#empty_undo_buffer) to avoid desynchronizing
+--   the undo buffer with the buffer text.
+--   The default value is `true`.
 -- @field use_tabs (bool)
---   Whether tabs will be used in indentation.
---   The default is `true`. `false` will only use space characters.
+--   Use tabs or spaces in indentation.
+--   The default value is `true`, for using tabs.
 -- @field v_scroll_bar (bool)
---   Whether the vertical scroll bar is visible.
---   Set to `false` to never see it and `true` to enable it again. The default
---   state is to display it when required.
+--   Display the vertical scroll bar.
+--   The default value is `true`.
 -- @field view_eol (bool)
---   Whether the end of line characters are visible.
---   Normally, the end of line characters are hidden.
+--   Display end of line characters.
+--   The default value is `false`.
 -- @field view_ws (number)
---   The visibility of white space characters.
+--   The whitespace character visibility mode.
 --
 --   * `_SCINTILLA.constants.SCWS_INVISIBLE` (0)
---     The normal display mode with white space displayed as an empty background
---     color.
+--     Whitespace is invisible.
 --   * `_SCINTILLA.constants.SCWS_VISIBLEALWAYS` (1)
---     White space characters are drawn as dots and arrows.
+--     Display whitespace as dots and arrows.
 --   * `_SCINTILLA.constants.SCWS_VISIBLEAFTERINDENT` (2)
---     White space used for indentation is displayed normally but after the
---     first visible character, it is shown as dots and arrows.
+--     Display non-indentation whitespace as dots and arrows.
+--
+--   The default value is `0`.
 -- @field virtual_space_options (number)
---   Virtual space options.
+--   The virtual space mode.
 --
 --   * `_SCINTILLA.constants.SCVS_NONE` (0)
---     Disables all use of virtual space (default).
+--     Disable virtual space.
 --   * `_SCINTILLA.constants.SCVS_RECTANGULARSELECTION` (1)
---     Enabled only for rectangular selections.
+--     Enable virtual space only for rectangular selections.
 --   * `_SCINTILLA.constants.SCVS_USERACCESSIBLE` (2)
---     Enabled.
+--     Enable virtual space.
+--
+--   The default value is `0`.
 -- @field whitespace_chars (string)
---   The set of characters making up whitespace for when moving or selecting by
---   word.
---   Use after setting `buffer.word_chars`.
+--   The set of characters considered to be whitespace characters when moving
+--   or selecting text by word.
+--   Set this only after setting [`buffer.word_chars`](#word_chars).
+--   The default value is a string containing all non-newline characters less
+--   than ASCII value 33.
 -- @field whitespace_size (number)
---   The size of the dots used to mark space characters.
+--   The size of the dots in pixels used to represent space characters when
+--   whitespace is visible.
+--   The default value is `1`.
 -- @field word_chars (string)
---   The set of characters making up words when moving or selecting by word.
+--   The set of characters considered to be word characters when moving or
+--   selecting text by word.
+--   The default value is a string containing alphanumeric characters, an
+--   underscore, and all characters greater than ASCII value 127.
 -- @field wrap_indent_mode (number)
---   How wrapped sublines are placed.
---   Default is fixed.
+--   The wrapped line indent mode.
 --
 --   * `_SCINTILLA.constants.SC_WRAP_INDENT_FIXED` (0)
---     Wrapped sublines aligned to left of window plus amount set by
---     `buffer.wrap_start_indent`.
+--     Indent wrapped lines by [`buffer.wrap_start_indent`](#wrap_start_indent).
 --   * `_SCINTILLA.constants.SC_WRAP_INDENT_SAME` (1)
---     Wrapped sublines are aligned to first subline indent.
+--     Indent wrapped lines the same as the first line.
 --   * `_SCINTILLA.constants.SC_WRAP_INDENT_INDENT` (2)
---     Wrapped sublines are aligned to first subline indent plus one more level
---     of indentation.
+--     Indent wrapped lines one more level than the first line.
 -- @field wrap_mode (number)
---   Text word wrap mode.
+--   Long line wrap mode.
 --
 --   * `_SCINTILLA.constants.SC_WRAP_NONE` (0)
---     Disable line wrapping.
+--     Long lines are not wrapped.
 --   * `_SCINTILLA.constants.SC_WRAP_WORD` (1)
---     Enable wrapping on word boundaries.
+--     Wrap long lines at word boundaries.
 --   * `_SCINTILLA.constants.SC_WRAP_CHAR` (2)
---     Enable wrapping between any characters.
+--     Wrap long lines at character boundaries.
+--
+--   The default value is `0`.
 -- @field wrap_start_indent (number)
---   The start indent for wrapped lines.
+--   The number of spaces to indent wrapped lines by if
+--   [`buffer.wrap_indent_mode`](#wrap_indent_mode) is
+--   `_SCINTILLA.constants.SC_WRAP_INDENT_FIXED`.
+--   The default value is `0`.
 -- @field wrap_visual_flags (number)
---   The display mode of visual flags for wrapped lines.
+--   The wrapped line visual display mode.
 --
 --   * `_SCINTILLA.constants.SC_WRAPVISUALFLAG_NONE` (0)
 --     No visual flags.
 --   * `_SCINTILLA.constants.SC_WRAPVISUALFLAG_END` (1)
---     Visual flag at end of subline of a wrapped line.
+--     Show visual flag at the end of the line.
 --   * `_SCINTILLA.constants.SC_WRAPVISUALFLAG_START` (2)
---     Visual flag at begin of subline of a wrapped line.
---     Subline is indented by at least 1 to make room for the flag.
+--     Show visual flag at the beginning of the sub-line.
+--   * `_SCINTILLA.constants.SC_WRAPVISUALFLAG_MARGIN` (4)
+--     Show visual flag in the line number margin of the sub-line.
+--
+--   The default value is `0`.
 -- @field wrap_visual_flags_location (number)
---   The location of visual flags for wrapped lines.
+--   The wrapped line visual flag drawing mode.
 --
 --   * `_SCINTILLA.constants.SC_WRAPVISUALFLAGLOC_DEFAULT` (0)
---     Visual flags drawn near border.
+--     Draw the visual flag near the right border.
 --   * `_SCINTILLA.constants.SC_WRAPVISUALFLAGLOC_END_BY_TEXT` (1)
---     Visual flag at end of subline drawn near text.
+--     Draw the visual flag near text at the end of the line.
 --   * `_SCINTILLA.constants.SC_WRAPVISUALFLAGLOC_START_BY_TEXT` (2)
---     Visual flag at beginning of subline drawn near text.
+--     Draw the visual flag near text at the beginning of the subline.
+--
+--   The default value is `0`.
 -- @field x_offset (number)
---   The horizontal scroll position.
+--   The horizontal scroll position in pixels.
 --   A value of `0` is the normal position with the first text column visible at
 --   the left of the view.
 -- @field zoom (number)
---   The number of points added to the size of all fonts.
---   It may be positive to magnify or negative to reduce.
+--   The number of points to add to the size of all fonts.
+--   Negative values are allowed.
+--   The default value is `0`.
 module('buffer')
 
 ---
--- Add a selection from anchor to caret as the main selection.
--- Retainings all other selections as additional selections. Since there is
--- always at least one selection, to set a list of selections, the first
--- selection should be added with `buffer:set_selection()` and later selections
--- added with this function.
+-- Adds a new selection to a text range from *anchor* to *caret* as the main
+-- selection, retaining all other selections as additional selections.
+-- Even if no text is selected, the current position counts as an empty
+-- selection. Use `buffer:set_selection()` first when setting a list of
+-- selections.
 -- @param buffer The global buffer.
 -- @param caret The caret.
 -- @param anchor The anchor.
 function add_selection(buffer, caret, anchor) end
 
 ---
--- Add text to the document at current position.
--- The current position is set at the end of the inserted text, but it is not
--- scrolled into view.
+-- Adds string *text* to the buffer at the current position and moves the
+-- current position to the end of the added text, but does not scroll it into
+-- view.
 -- @param buffer The global buffer.
 -- @param text The text to add.
 function add_text(buffer, text) end
 
 ---
--- Enlarge the document to a particular size of text bytes.
--- The document will not be made smaller than its current contents.
+-- Enlarges the buffer to store *bytes* number of bytes, but never shrinks it
+-- beyond the size of its contents.
 -- @param buffer The global buffer.
--- @param bytes The number of bytes the document can store.
+-- @param bytes The number of bytes the buffer can store.
 function allocate(buffer, bytes) end
 
 ---
--- Clear the annotations from all lines.
+-- Clears annotations from all lines.
 -- @param buffer The global buffer.
 function annotation_clear_all(buffer) end
 
 ---
--- Append a string to the end of the document without changing the selection.
--- The current selection is not changed and the new text is not scrolled into
--- view.
+-- Appends string *text* to the end of the buffer without changing the selected
+-- text or scrolling the text into view.
 -- @param buffer The global buffer.
 -- @param text The text.
 function append_text(buffer, text) end
 
 ---
--- Is there an auto-completion list visible?
+-- Returns whether or not an autocompletion list is visible.
 -- @param buffer The global buffer.
 -- @return bool
 function auto_c_active(buffer) end
 
 ---
--- Remove the auto-completion list from the screen.
--- A set of characters that will cancel autocompletion can be specified with
--- `buffer:auto_c_stops()`.
+-- Cancels the autocompletion list.
 -- @param buffer The global buffer.
 function auto_c_cancel(buffer) end
 
 ---
--- User has selected an item so remove the list and insert the selection.
--- This has the same effect as the tab key.
+-- Autocompletes the selected word in the list.
 -- @param buffer The global buffer.
 function auto_c_complete(buffer) end
 
 ---
--- Retrieve the position of the caret when the auto-completion list was
--- displayed.
+-- Returns the position where autocompletion started at.
 -- @param buffer The global buffer.
 -- @return number
 function auto_c_pos_start(buffer) end
 
 ---
--- Select the item in the auto-completion list that starts with a string.
--- By default, comparisons are case sensitive, but this can change with
--- `buffer.auto_c_ignore_case`.
+-- Selects the first item in the autocompletion list that starts with *string*,
+-- considering case sensitiveness depending 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
 
 ---
--- Display an auto-completion list.
+-- Displays an autocompletion list from *item_list*, a sorted string whose items
+-- are delimited by `buffer.auto_c_separator` characters, using *len_entered*
+-- number of characters behind the caret as the prefix of the word to
+-- autocomplete.
 -- @param buffer The global buffer.
 -- @param len_entered The number of characters before the caret used to provide
 --   the context.
--- @param item_list List of words separated by separator characters (initially
---   spaces). The list of words should be in sorted order.
+-- @param item_list Sorted list of words separated by separator characters
+--   (initially spaces).
 function auto_c_show(buffer, len_entered, item_list) end
 
 ---
--- Define a set of characters that when typed cancel the auto-completion list.
+-- Defines *chars* as the set of characters that cancel autocompletion when
+-- typed.
+-- The default set is an empty string.
 -- @param buffer The global buffer.
 -- @param chars String list of characters. This list is empty by default.
 function auto_c_stops(buffer, chars) end
 
 ---
--- Dedent the selected lines.
+-- Dedents the selected lines.
 -- @param buffer The global buffer.
 function back_tab(buffer) end
 
 ---
--- Start a sequence of actions that is undone and redone as a unit.
+-- Starts a sequence of actions to undo or redo as a single action.
 -- May be nested.
 -- @param buffer The global buffer.
 function begin_undo_action(buffer) end
 
 ---
--- Highlight the character at a position indicating there is no matching brace.
+-- Highlights the character at position *pos* as an unmatched brace character in
+-- the `_SCINTILLA.constants.STYLE_BRACEBAD` style.
+-- Removes highlighting when *pos* is `-1`.
 -- @param buffer The global buffer.
 -- @param pos The position or `-1` to remove the highlight.
 function brace_bad_light(buffer, pos) end
 
 ---
--- Use specified indicator to highlight non matching brace instead of changing
--- its style.
+-- Highlights unmatched brace characters with indicator number *indic_num*, in
+-- the range of `0` to `31`, instead of the
+-- `_SCINTILLA.constants.STYLE_BRACEBAD` style if *use_indicator* is `true`.
 -- @param buffer The global buffer.
 -- @param use_indicator Use an indicator.
 -- @param indic_num The indicator number.
 function brace_bad_light_indicator(buffer, use_indicator, indic_num) end
 
 ---
--- Highlight the characters at two positions.
--- If indent guides are enabled, the indent that corresponds with the brace can
--- be highlighted by locating the column with `buffer.column` and highlight the
--- indent with `buffer.highlight_guide`.
+-- Highlights the characters at positions *pos1* and *pos2* as matching braces
+-- in the `_SCINTILLA.constants.STYLE_BRACELIGHT` style.
+-- If indent guides are enabled, locate the column with `buffer.column` and
+-- set `buffer.highlight_guide` in order to highlight the indent guide.
 -- @param buffer The global buffer.
 -- @param pos1 The first position.
 -- @param pos2 The second position.
 function brace_highlight(buffer, pos1, pos2) end
 
 ---
--- Use specified indicator to highlight matching braces instead of changing
--- their style.
+-- Highlights matching brace characters with indicator number *indic_num*, in
+-- the range of `0` to `31`, instead of the
+-- `_SCINTILLA.constants.STYLE_BRACELIGHT` style if *use_indicator* is `true`.
 -- @param buffer The global buffer.
 -- @param use_indicator Use an indicator.
 -- @param indic_num The indicator number.
 function brace_highlight_indicator(buffer, use_indicator, indic_num) end
 
 ---
--- Find the position of a matching brace or `-1` if no match.
--- The brace characters handled are '(', ')', '[', ']', '{', '}', '<', and '>'.
--- The search is forwards from an opening brace and backwards from a closing
--- brace. A match only occurs if the style of the matching brace is the same as
--- the starting brace or the matching brace is beyond the end of styling. Nested
--- braces are handled correctly.
+-- Returns the position of the matching brace for the brace character at
+-- position *pos*, taking nested braces into account, or `-1`.
+-- The brace characters recognized are '(', ')', '[', ']', '{', '}', '<', and
+-- '>' and must have the same style.
 -- @param buffer The global buffer.
 -- @param pos The position.
 -- @return number.
 function brace_match(buffer, pos) end
 
 ---
--- Is there an active call tip?
+-- Returns whether or not a call tip is visible.
 -- @param buffer The global buffer.
 -- @return bool
 function call_tip_active(buffer) end
 
 ---
--- Remove the call tip from the screen.
--- Call tips are also removed if any keyboard commands that are not compatible
--- with editing the argument list of a function are used.
+-- Removes the call tip from view.
 -- @param buffer The global buffer.
 function call_tip_cancel(buffer) end
 
 ---
--- Retrieve the position where the caret was before displaying the call tip.
+-- Returns the position where the call tip displayed at.
 -- @param buffer The global buffer.
 -- @return number
 function call_tip_pos_start(buffer) end
 
 ---
--- Highlights a segment of a call tip.
+-- Highlights call tip text from *start_pos*, starting from zero, to *end_pos*
+-- with the color `buffer.call_tip_fore_hlt`.
 -- @param buffer The global buffer.
 -- @param start_pos The start position.
 -- @param end_pos The end position.
 function call_tip_set_hlt(buffer, start_pos, end_pos) end
 
 ---
--- Show a call tip containing a definition near position pos.
--- The call tip text is aligned to start 1 line below this character unless up
--- and/or down arrows have been included in the call tip text in which case the
--- tip is aligned to the right-hand edge of the rightmost arrow. The assumption
--- is that the text starts with something like `"\001 1 of 3 \002"`.
+-- Displays a call tip containing string *text* for the word behind position
+-- *pos*.
+-- Any "\001" or "\002" bytes in *text* are replaced by arrow visuals,
+-- indicating the word has more than one call tip.
 -- @param buffer The global buffer.
 -- @param pos The position.
 -- @param text The text.
 function call_tip_show(buffer, pos, text) end
 
 ---
--- Will a paste succeed?
+-- Returns whether or not the clipboard has text to paste.
 -- @param buffer The global buffer.
 -- @return bool
 function can_paste(buffer) end
 
 ---
--- Are there any redoable actions in the undo history?
+-- Returns whether or not there is an action to redo.
 -- @param buffer The global buffer.
 -- @return bool
 function can_redo(buffer) end
 
 ---
--- Are there any undoable actions in the undo history?
+-- Returns whether or not there is an action to undo.
 -- @param buffer The global buffer.
 -- @return bool
 function can_undo(buffer) end
 
 ---
--- Cancel any modes such as call tip or auto-completion list display.
+-- Cancels the active call tip, autocompletion list, user list, selection mode,
+-- etc.
 -- @param buffer The global buffer.
 function cancel(buffer) end
 
 ---
--- Indicate that the internal state of a lexer has changed over a range and
--- therefore there may be a need to redraw.
+-- Tells the lexer to re-process the range of text from *start_pos* to
+-- *end_pos*.
 -- @param buffer The global buffer.
 -- @param start_pos The start position.
 -- @param end_pos The end position.
 function change_lexer_state(buffer, start_pos, end_pos) end
 
 ---
--- Move caret left one character.
+-- Moves the caret left one character.
 -- @param buffer The global buffer.
 function char_left(buffer) end
 
 ---
--- Move caret left one character extending selection to new caret position.
+-- Moves the caret left one character, extending the selection to the new
+-- position.
 -- @param buffer The global buffer.
 function char_left_extend(buffer) end
 
 ---
--- Move caret left one character, extending rectangular selection to new caret
--- position.
+-- Moves the caret left one character, extending the rectangular selection to
+-- the new position.
 -- @param buffer The global buffer.
 function char_left_rect_extend(buffer) end
 
 ---
--- Find the position of a character from a point within the window.
+-- Returns the character position closest to view coordinates *x* and *y*.
 -- @param buffer The global buffer.
--- @param x The x-coordinate in the window.
--- @param y The y-coordinate in the window.
+-- @param x The x-coordinate in the view.
+-- @param y The y-coordinate in the view.
 -- @return number
 function char_position_from_point(buffer, x, y) end
 
 ---
--- Find the position of a character from a point within the window.
--- Return `-1` if not close to text.
+-- Returns the character position closest to view coordinates *x* and *y*, or
+-- `-1` if the point is outside the window or not close to any text.
 -- @param buffer The global buffer.
--- @param x The x-coordinate in the window.
--- @param y The y-coordinate in the window.
+-- @param x The x-coordinate in the view.
+-- @param y The y-coordinate in the view.
 -- @return number
 function char_position_from_point_close(buffer, x, y) end
 
 ---
--- Move caret right one character.
+-- Moves the caret right one character.
 -- @param buffer The global buffer.
 function char_right(buffer) end
 
 ---
--- Move caret right one character extending selection to new caret position.
+-- Moves the caret right one character, extending the selection to the new
+-- position.
 -- @param buffer The global buffer.
 function char_right_extend(buffer) end
 
 ---
--- Move caret right one character, extending rectangular selection to new caret
--- position.
+-- Moves the caret right one character, extending the rectangular selection to
+-- the new position.
 -- @param buffer The global buffer.
 function char_right_rect_extend(buffer) end
 
 ---
--- Set the last x chosen value to be the caret x position.
--- The view remembers the x value of the last position horizontally moved to
--- explicitly by the user and this value is then used when moving vertically
--- such as by using the up and down keys. This function sets the current x
--- position of the caret as the remembered value.
+-- Sets the preferred horizontal position of the caret when moving between
+-- lines to the current position.
 -- @param buffer The global buffer.
+-- @see caret_sticky
 function choose_caret_x(buffer) end
 
 ---
--- Clear the selection.
+-- Deletes the selected text or the character at the current position.
 -- @param buffer The global buffer.
 function clear(buffer) end
 
 ---
--- Delete all text in the document.
+-- Deletes all of the text in the buffer unless the buffer is read-only.
 -- @param buffer The global buffer.
 function clear_all(buffer) end
 
 ---
--- Drop all key mappings.
+-- Clears Scintilla's internal key bindings.
 -- @param buffer The global buffer.
 function clear_all_cmd_keys(buffer) end
 
 ---
--- Set all style bytes to `0`, remove all folding information.
+-- Clears all styling and folding information in the buffer.
 -- @param buffer The global buffer.
 function clear_document_style(buffer) end
 
 ---
--- Clear all the registered XPM images.
+-- Clears all images registered using `buffer:register_image()` and
+-- `buffer:register_rgba_image()`.
 -- @param buffer The global buffer.
 function clear_registered_images(buffer) end
 
 ---
--- Clear selections to a single empty stream selection.
+-- Removes all selections and moves the caret to the beginning of the buffer.
 -- @param buffer The global buffer.
 function clear_selections(buffer) end
 
 ---
--- Colorise a segment of the document using the current lexing language.
+-- Tells the lexer to style and fold the range of text from *start_pos* to
+-- *end_pos*.
+-- If *end_pos* is `-1`, styles and folds to the end of the buffer.
 -- @param buffer The global buffer.
 -- @param start_pos The start position.
 -- @param end_pos The end position or `-1` to style from `start_pos` to the end
@@ -1196,16 +1268,15 @@ function clear_selections(buffer) end
 function colourise(buffer, start_pos, end_pos) end
 
 ---
--- Find the next line at or after line_start that is a contracted fold header
--- line.
--- Return `-1` when no more lines.
+-- Returns the line number of the next contracted fold header line starting at
+-- *line_start*, or `-1`.
 -- @param buffer The global buffer.
 -- @param line_start The start line number.
 -- @return number
 function contracted_fold_next(buffer, line_start) end
 
 ---
--- Converts all line endings in the document to one mode.
+-- Converts all line endings to end of line mode *mode*.
 -- @param buffer The global buffer.
 -- @param mode The line ending mode. Valid values are:
 --   * `_SCINTILLA.constants.SC_EOL_CRLF` (0)
@@ -1214,31 +1285,34 @@ function contracted_fold_next(buffer, line_start) end
 function convert_eo_ls(buffer, mode) end
 
 ---
--- Copy the selection to the clipboard.
+-- Copies the selected text to the clipboard.
+-- Multiple selections are copied in order with no delimiters. Rectangular
+-- selections are copied from top to bottom with line ending delimiters. Virtual
+-- space is not copied.
 -- @param buffer The global buffer.
 function copy(buffer) end
 
 ---
--- Copy the selection, if selection empty copy the line with the caret.
+-- Copies the selected text or the current line to the clipboard.
 -- @param buffer The global buffer.
 function copy_allow_line(buffer) end
 
 ---
--- Copy a range of text to the clipboard. Positions are clipped into the
--- document.
+-- Copies the range of text from *start_pos* to *end_pos* to the clipboard.
 -- @param buffer The global buffer.
 -- @param start_pos The start position.
 -- @param end_pos The end position.
 function copy_range(buffer, start_pos, end_pos) end
 
 ---
--- Copy argument text to the clipboard.
+-- Copies string *text* to the clipboard.
 -- @param buffer The global buffer.
 -- @param text The text.
 function copy_text(buffer, text) end
 
 ---
--- Count characters between two positions.
+-- Returns the number of whole characters in-between positions *start_pos* and
+-- *end_pos*.
 -- @param buffer The global buffer.
 -- @param start_pos The start position.
 -- @param end_pos The end position.
@@ -1246,216 +1320,232 @@ function copy_text(buffer, text) end
 function count_characters(buffer, start_pos, end_pos) end
 
 ---
--- Cut the selection to the clipboard.
+-- Cuts the selected text to the clipboard.
+-- Multiple selections are copied in order with no delimiters. Rectangular
+-- selections are copied from top to bottom with line ending delimiters. Virtual
+-- space is not copied.
 -- @param buffer The global buffer.
 function cut(buffer) end
 
 ---
--- Delete back from the current position to the start of the line.
+-- Deletes text from the current position to the beginning of the line.
 -- @param buffer The global buffer.
 function del_line_left(buffer) end
 
 ---
--- Delete forwards from the current position to the end of the line.
+-- Deletes text from the current position to the end of the line.
 -- @param buffer The global buffer.
 function del_line_right(buffer) end
 
 ---
--- Delete the word to the left of the caret.
+-- Deletes the word to the left of the caret, including any leading non-word
+-- characters.
+-- `buffer.word_chars` contains word characters.
 -- @param buffer The global buffer.
 function del_word_left(buffer) end
 
 ---
--- Delete the word to the right of the caret.
+-- Deletes the word to the right of the caret, including any trailing non-word
+-- characters.
+-- `buffer.word_chars` contains word characters.
 -- @param buffer The global buffer.
 function del_word_right(buffer) end
 
 ---
--- Delete the word to the right of the caret, but not the trailing non-word
+-- Deletes the word to the right of the caret, excluding any trailing non-word
 -- characters.
+-- `buffer.word_chars` contains word characters.
 -- @param buffer The global buffer.
 function del_word_right_end(buffer) end
 
 ---
--- Delete the selection or if no selection, the character before the caret.
+-- Deletes the selected text or the character behind the caret.
 -- @param buffer The global buffer.
 function delete_back(buffer) end
 
 ---
--- Delete the selection or if no selection, the character before the caret.
--- Will not delete the character before at the start of a line.
+-- Deletes the selected text or the character behind the caret unless the caret
+-- is at the beginning of a line.
 -- @param buffer The global buffer.
 function delete_back_not_line(buffer) end
 
 ---
--- Delete a range of text in the document.
+-- Deletes the range of text from *pos* to *pos* + *length* in the buffer.
 -- @param buffer The global buffer.
 -- @param pos The start position of the range to delete.
 -- @param length The length of the range to delete.
 function delete_range(buffer, pos, length) end
 
 ---
--- Find the document line of a display line taking hidden lines into account.
+-- Returns the actual line number of displayed line number *display_line*,
+-- taking hidden lines into account.
+-- If *display_line* is less than or equal to zero, returns `0`. If
+-- *display_line* is greater than or equal to the number of displayed lines,
+-- returns `buffer.line_count`.
 -- @param buffer The global buffer.
+-- @param display_line The display line number.
 -- @return number
-function doc_line_from_visible(buffer) end
+function doc_line_from_visible(buffer, display_line) end
 
 ---
--- Move caret to last position in document.
+-- Moves the caret to the end of the buffer.
 -- @param buffer The global buffer.
 function document_end(buffer) end
 
 ---
--- Move caret to last position in document extending selection to new caret
+-- Moves the caret to the end of the buffer, extending the selection to the new
 -- position.
 -- @param buffer The global buffer.
 function document_end_extend(buffer) end
 
 ---
--- Move caret to first position in document.
+-- Moves the caret to the beginning of the buffer.
 -- @param buffer The global buffer.
 function document_start(buffer) end
 
 ---
--- Move caret to first position in document extending selection to new caret
--- position.
+-- Moves the caret to the beginning of the buffer, extending selection to the
+-- new position.
 -- @param buffer The global buffer.
 function document_start_extend(buffer) end
 
 ---
--- Switch from insert to overtype mode or the reverse.
+-- Toggles `buffer.overtype`.
 -- @param buffer The global buffer.
 function edit_toggle_overtype(buffer) end
 
 ---
--- Delete the undo history.
--- It also sets the save point to the start of the undo buffer, so the document
--- will appear to be unmodified.
+-- Deletes the undo and redo history and sets `buffer.modify` to `false`.
 -- @param buffer The global buffer.
 function empty_undo_buffer(buffer) end
 
 ---
--- Translates a UTF8 string into the document encoding.
--- Return the length of the result in bytes. On error return `0`.
+-- Returns the result of UTF-8-encoded string *string* converted into the
+-- buffer's encoding.
 -- @param buffer The global buffer.
 -- @param string The string.
 -- @return number
 function encoded_from_utf8(buffer, string) end
 
 ---
--- End a sequence of actions that is undone and redone as a unit.
+-- Ends a sequence of actions to undo or redo as a single action.
 -- @param buffer The global buffer.
 function end_undo_action(buffer) end
 
 ---
--- Ensure a particular line is visible by expanding any header line hiding it.
+-- Ensures line number *line* is visible by expanding any fold header lines
+-- hiding it.
 -- @param buffer The global buffer.
 -- @param line The line number.
 function ensure_visible(buffer, line) end
 
 ---
--- Ensure a particular line is visible by expanding any header line hiding it.
--- Use the currently set visibility policy to determine which range to display.
+-- Ensures line number *line* is visible by expanding any fold header lines
+-- hiding it and applies the vertical caret policy set with
+-- `buffer:set_visible_policy()`.
 -- @param buffer The global buffer.
 -- @param line The line number.
 function ensure_visible_enforce_policy(buffer, line) end
 
 ---
--- Find the position of a column on a line taking into account tabs and
--- multi-byte characters.
--- If beyond end of line, return line end position.
+-- Returns the position of column number *column* on line number *line*, taking
+-- tab and multi-byte characters into account, or the position at the end of
+-- line *line*.
 -- @param buffer The global buffer.
 -- @param line The line number.
 -- @param column The column number.
 function find_column(buffer, line, column) end
 
 ---
--- Insert a Form Feed character.
+-- Inserts a Form Feed ("\f") character at the current position.
 -- @param buffer The global buffer.
 function form_feed(buffer) end
 
 ---
--- Retrieve the text of the line containing the caret.
--- Also returns the index of the caret on the line.
+-- Returns the current line's text and the index of the caret on the line,
+-- starting from zero.
 -- @param buffer The global buffer.
 -- @return string, number
 function get_cur_line(buffer) end
 
 ---
--- Get the back color for active hotspots in "0xBBGGRR" format.
+-- Returns the numeric background color for active hotspots.
 -- @param buffer The global buffer.
 -- @return number
 function get_hotspot_active_back(buffer) end
 
 ---
--- Get the fore color for active hotspots.
+-- Returns the numeric foreground color for active hotspots.
 -- @param buffer The global buffer.
 -- @return number
 function get_hotspot_active_fore(buffer) end
 
 ---
--- Find the last child line of a header line.
+-- Returns the line number of the last line after line number *start_line* whose
+-- fold level is greater than *level* or the level of *start_line* if *level* is
+-- `-1`.
 -- @param buffer The global buffer.
--- @param header_line The line number of a header line.
--- @param level The level or `-1` for the level of `header_line`.
-function get_last_child(buffer, header_line, level) end
+-- @param start_line The line number of a header line.
+-- @param level The level or `-1` for the level of `start_line`.
+function get_last_child(buffer, start_line, level) end
 
 ---
--- Retrieve the contents of a line.
--- Also returns the length of the line.
+-- Returns the text on line number *line*, including end of line characters, and
+-- the length of the line.
 -- @param buffer The global buffer.
 -- @param line The line number.
 -- @return string, number
 function get_line(buffer, line) end
 
 ---
--- Retrieve the position of the end of the selection at the given line (`-1` if
--- no selection on this line).
+-- Returns the position of the end of the selected text on line number *line*,
+-- or `-1`.
 -- @param buffer The global buffer.
 -- @param line The line number.
 function get_line_sel_end_position(buffer, line) end
 
 ---
--- Retrieve the position of the start of the selection at the given line (`-1`
--- if no selection on this line).
+-- Returns the position of the beginning of the selected text on line number
+-- *line*, or `-1`.
 -- @param buffer The global buffer.
 -- @param line The line number.
 function get_line_sel_start_position(buffer, line) end
 
 ---
--- Retrieve the selected text.
--- Also returns the length of the text.
+-- Returns the selected text and its length.
+-- Multiple selections are included in order with no delimiters. Rectangular
+-- selections are included from top to bottom with line ending delimiters.
+-- Virtual space is not included.
 -- @param buffer The global buffer.
 -- @return string, number
 function get_sel_text(buffer) end
 
 ---
--- Retrieve all the text in the document.
--- Also returns number of characters retrieved.
+-- Returns all of the text in the buffer and its length.
 -- @param buffer The global buffer.
 function get_text(buffer) end
 
 ---
--- Set caret to start of a line and ensure it is visible.
+-- Places the caret an anchor at the beginning of line number *line* and scrolls
+-- them into view.
 -- @param buffer The global buffer.
 -- @param line The line number.
 function goto_line(buffer, line) end
 
 ---
--- Set caret to a position and ensure it is visible.
--- The anchor position is set the same as the current position.
+-- Places the caret and anchor at position *pos* and scrolls them into view.
 -- @param buffer The global buffer.
 -- @param pos The position.
 function goto_pos(buffer, pos) end
 
 ---
--- Set the focus to this view.
+-- Sets the focus to the buffer's view.
 -- @param buffer The global buffer.
 function grab_focus(buffer) end
 
 ---
--- Make a range of lines invisible.
--- This has no effect on fold levels or fold flags. `start_line` can not be
+-- Hides the range of lines from line number *start_line* to *end_line*.
+-- This has no effect on fold levels or fold flags and the first line cannot be
 -- hidden.
 -- @param buffer The global buffer.
 -- @param start_line The start line.
@@ -1463,91 +1553,93 @@ function grab_focus(buffer) end
 function hide_lines(buffer, start_line, end_line) end
 
 ---
--- Draw the selection in normal style or with selection highlighted.
+-- Do not highlight selected text if *normal* is `true`.
 -- @param buffer The global buffer.
 -- @param normal Draw normal selection.
 function hide_selection(buffer, normal) end
 
 ---
--- Move caret to first position on line.
+-- Moves the caret to the beginning of the current line.
 -- @param buffer The global buffer.
 function home(buffer) end
 
 ---
--- Move caret to first position on display line.
+-- Moves the caret to the beginning of the current wrapped line.
 -- @param buffer The global buffer.
 function home_display(buffer) end
 
 ---
--- Move caret to first position on display line extending selection to new caret
--- position.
+-- Moves the caret to the beginning of the current wrapped line, extending the
+-- selection to the new position.
 -- @param buffer The global buffer.
 function home_display_extend(buffer) end
 
 ---
--- Move caret to first position on line extending selection to new caret
--- position.
+-- Moves the caret to the beginning of the current line, extending selection to
+-- the new position.
 -- @param buffer The global buffer.
 function home_extend(buffer) end
 
 ---
--- Move caret to first position on line, extending rectangular selection to new
--- caret position.
+-- Moves the caret to beginning of the current line, extending the rectangular
+-- selection to the new position.
 -- @param buffer The global buffer.
 function home_rect_extend(buffer) end
 
 ---
--- Move caret to the start of the display line when word-wrap is enabled.
--- If already there, go to the start of the document line.
+-- Moves the caret to beginning of the current wrapped line, or if already
+-- there, to the beginning of the actual line.
 -- @param buffer The global buffer.
 function home_wrap(buffer) end
 
 ---
--- Like `buffer:home_wrap()` but extending selection to new caret position.
+-- Like `buffer:home_wrap()`, but extends the selection to the new position.
 -- @param buffer The global buffer.
 function home_wrap_extend(buffer) end
 
 ---
--- Retrieve a bitmap value representing which indicators are non-zero at a
--- position.
--- Bit 0 is set if indicator 0 is present, bit 1 for indicator 1 and so on.
+-- Returns a bit-mask representing which indicators are on at position *pos*.
+-- Bit 0 is set if indicator 0 is on, bit 1 for indicator 1, etc.
 -- @param buffer The global buffer.
 -- @param pos The position.
 -- @return number
 function indicator_all_on_for(buffer, pos) end
 
 ---
--- Turn a indicator off over a range.
+-- Clears indicator `buffer.indicator_current` over the range of text from *pos*
+-- to *pos* + *clear_length*.
 -- @param buffer The global buffer.
 -- @param pos The start position.
 -- @param clear_length The length.
 function indicator_clear_range(buffer, pos, clear_length) end
 
 ---
--- Find the position where a particular indicator ends.
+-- Returns the end position of indicator number *indicator*, in the range of `0`
+-- to `31`, at position *pos*.
 -- @param buffer The global buffer.
 -- @param indicator An indicator number in the range of `0` to `31`.
 -- @param pos The position of the indicator.
 function indicator_end(buffer, indicator, pos) end
 
 ---
--- Turn a indicator on over a range.
--- This function fills with the current indicator value.
+-- Sets indicator `buffer.indicator_value` or `buffer.indicator_current` over
+-- the range of text from *pos* to *pos* + *fill_length*.
 -- @param buffer The global buffer.
 -- @param pos The start position.
 -- @param fill_length The length.
 function indicator_fill_range(buffer, pos, fill_length) end
 
 ---
--- Find the position where a particular indicator starts.
+-- Returns the position of the beginning of indicator number *indicator*, in the
+-- range of `0` to `31`, at position *pos*.
 -- @param buffer The global buffer.
 -- @param indicator An indicator number in the range of `0` to `31`.
 -- @param pos The position of the indicator.
 function indicator_start(buffer, indicator, pos) end
 
 ---
--- Retrieve the value of a particular indicator at a position.
--- Currently all values are drawn the same.
+-- Returns the value of indicator number *indicator*, in the range of `0` to
+-- `31`, at position *pos*.
 -- @param buffer The global buffer.
 -- @param indicator The indicator number in the range of `0` to `31`.
 -- @param pos The position.
@@ -1555,99 +1647,103 @@ function indicator_start(buffer, indicator, pos) end
 function indicator_value_at(buffer, indicator, pos) end
 
 ---
--- Insert string at a position.
--- If the current position is after the insertion point then it is moved along
--- with its surrounding text but no scrolling is performed.
+-- Inserts string *text* at position *pos* or the current position if *pos* is
+-- `-1`.
+-- If the current position is after the *pos*, it is moved appropriately, but
+-- not scrolled into view.
 -- @param buffer The global buffer.
 -- @param pos The position to insert text at or `-1` for the current position.
 -- @param text The text to insert.
 function insert_text(buffer, pos, text) end
 
 ---
--- Copy the line containing the caret.
+-- Copies the current line to the clipboard.
 -- @param buffer The global buffer.
 function line_copy(buffer) end
 
 ---
--- Cut the line containing the caret.
+-- Cuts the current line to the clipboard.
 -- @param buffer The global buffer.
 function line_cut(buffer) end
 
 ---
--- Delete the line containing the caret.
+-- Deletes the current line.
 -- @param buffer The global buffer.
 function line_delete(buffer) end
 
 ---
--- Move caret down one line.
+-- Moves the caret down one line.
 -- @param buffer The global buffer.
 function line_down(buffer) end
 
 ---
--- Move caret down one line extending selection to new caret position.
+-- Moves the caret down one line, extending the selection to the new position.
 -- @param buffer The global buffer.
 function line_down_extend(buffer) end
 
 ---
--- Move caret down one line, extending rectangular selection to new caret
+-- Moves the caret down one line, extending the rectangular selection to the new
 -- position.
 -- @param buffer The global buffer.
 function line_down_rect_extend(buffer) end
 
 ---
--- Duplicate the current line.
+-- Duplicates the current line below the line.
 -- @param buffer The global buffer.
 function line_duplicate(buffer) end
 
 ---
--- Move caret to last position on line.
+-- Moves the caret to the end of the current line.
 -- @param buffer The global buffer.
 function line_end(buffer) end
 
 ---
--- Move caret to last position on display line.
+-- Moves the caret to the end of the current wrapped line.
 -- @param buffer The global buffer.
 function line_end_display(buffer) end
 
 ---
--- Move caret to last position on display line extending selection to new caret
--- position.
+-- Moves the caret to the end of the current wrapped line, extending the
+-- selection to the new position.
 -- @param buffer The global buffer.
 function line_end_display_extend(buffer) end
 
 ---
--- Move caret to last position on line extending selection to new caret
--- position.
+-- Moves the caret to the end of the current line, extending the selection to
+-- the new position.
 -- @param buffer The global buffer.
 function line_end_extend(buffer) end
 
 ---
--- Move caret to last position on line, extending rectangular selection to new
--- caret position.
+-- Moves the caret to the end of the current line, extending the rectangular
+-- selection to the new position.
 -- @param buffer The global buffer.
 function line_end_rect_extend(buffer) end
 
 ---
--- Move caret to the end of the display line when word-wrap is enabled.
--- If already there, go to the end of the document line.
+-- Moves the caret to the end of the current wrapped line, or if already there,
+-- to the end of the actual line.
 -- @param buffer The global buffer.
 function line_end_wrap(buffer) end
 
 ---
--- Like `buffer:line_end_wrap()` but extending selection to new caret position.
+-- Like `buffer:line_end_wrap()`, but extends the selection to the new position.
 -- @param buffer The global buffer.
 function line_end_wrap_extend(buffer) end
 
 ---
--- Retrieve the line containing a position.
+-- Returns the line number containing position *pos*.
+-- Returns `0` if *pos* is less than 0 or `buffer.line_count` if *pos* is
+-- greater than `buffer.length`.
 -- @param buffer The global buffer.
 -- @param pos The position.
 -- @return number
 function line_from_position(buffer, pos) end
 
 ---
--- Returns how many characters are on a line, including end of line characters.
--- To get the length of the line not including any end of line characters, use
+-- Returns the number of characters on line number *line*, including end of line
+-- characters.
+-- To get line length excluding end of line characters, use
 -- `buffer.line_end_position[line] - buffer:position_from_line(line)`.
 -- @param buffer The global buffer.
 -- @param line The line number.
@@ -1655,70 +1751,72 @@ function line_from_position(buffer, pos) end
 function line_length(buffer, line) end
 
 ---
--- Scroll horizontally and vertically.
+-- Scroll right *columns* columns and down *lines* lines.
+-- Negative values are allowed.
 -- @param buffer The global buffer.
 -- @param columns The number of columns to scroll horizontally.
 -- @param lines The number of lines to scroll vertically.
 function line_scroll(buffer, columns, lines) end
 
 ---
--- Scroll the document down, keeping the caret visible.
+-- Scroll the buffer down one line, keeping the current position visible.
 -- @param buffer The global buffer.
 function line_scroll_down(buffer) end
 
 ---
--- Scroll the document up, keeping the caret visible.
+-- Scroll the buffer up one line, keeping the current position visible.
 -- @param buffer The global buffer.
 function line_scroll_up(buffer) end
 
 ---
--- Switch the current line with the previous.
+-- Switch the current line with the previous one.
 -- @param buffer The global buffer.
 function line_transpose(buffer) end
 
 ---
--- Move caret up one line.
+-- Moves the caret up one line.
 -- @param buffer The global buffer.
 function line_up(buffer) end
 
 ---
--- Move caret up one line extending selection to new caret position.
+-- Moves the caret up one line, extending the selection to the new position.
 -- @param buffer The global buffer.
 function line_up_extend(buffer) end
 
 ---
--- Move caret up one line, extending rectangular selection to new caret
+-- Moves the caret up one line, extending the rectangular selection to the new
 -- position.
 -- @param buffer The global buffer.
 function line_up_rect_extend(buffer) end
 
 ---
--- Join the lines in the target.
--- Where this would lead to no space between words, an extra space is inserted.
+-- Joins the lines in the target range, inserting spaces in-between words on
+-- separate lines.
 -- @param buffer The global buffer.
 function lines_join(buffer) end
 
 ---
--- Split the lines in the target into lines that are less wide than
--- `pixel_width` where possible.
+-- Splits the lines in the target range into lines of width at most
+-- *pixel_width* or the width of the view if *pixel_width* is `0`.
 -- @param buffer The global buffer.
 -- @param pixel_width The pixel width. When `0`, the width of the view is used.
 function lines_split(buffer, pixel_width) end
 
 ---
--- Transform the selection to lower case.
+-- Converts the selected text to lower case letters.
 -- @param buffer The global buffer.
 function lower_case(buffer) end
 
 ---
--- Clear the margin text on all lines.
+-- Clears margin text on all lines.
 -- @param buffer The global buffer.
 function margin_text_clear_all(buffer) end
 
 ---
--- Add a marker to a line, returning an ID which can be used to find or delete
--- the marker.
--- Returns `-1` if this fails (illegal line number, out of memory).
+-- Adds marker number *marker_num*, in the range of `0` to `31`, on line number
+-- *line*, returning a marker handle which can be used in
+-- `buffer:marker_delete_handle()` and `buffer:marker_line_from_handle()`, or
+-- `-1` if the marker cannot be added.
 -- @param buffer The global buffer.
 -- @param line The line number.
 -- @param marker_num A marker number in the range of `0` to `31`.
@@ -1726,7 +1824,9 @@ function margin_text_clear_all(buffer) end
 function marker_add(buffer, line, marker_num) end
 
 ---
--- Add a set of markers to a line.
+-- Adds the markers specified in the marker bit-mask *marker_mask* to line
+-- number *line*.
+-- Bit 0 is set to add marker 0, bit 1 for marker 1, etc., up to marker 31.
 -- @param buffer The global buffer.
 -- @param line The line number.
 -- @param marker_mask A mask of markers to set. Set bit 0 to set marker 0, bit
@@ -1734,7 +1834,8 @@ function marker_add(buffer, line, marker_num) end
 function marker_add_set(buffer, line, marker_mask) end
 
 ---
--- Set the symbol used for a particular marker number.
+-- Sets the symbol *marker_symbol* shown in the margin for marker number
+-- *marker_num*, in the range of `0` to `31`.
 -- @param buffer The global buffer.
 -- @param marker_num A marker number in the range of `0` to `31`.
 -- @param marker_symbol A marker symbol: `_SCINTILLA.constants.SC_MARK_*`.
@@ -1742,16 +1843,22 @@ function marker_add_set(buffer, line, marker_mask) end
 function marker_define(buffer, marker_num, marker_symbol) end
 
 ---
--- Define a marker from a pixmap.
+-- Defines XPM image *pixmap* for marker number *marker_num*, in the range of
+-- `0` to `31`.
+-- Pixmap markers use the `_SCINTILLA.constants.SC_MARK_PIXMAP` marker symbol.
 -- @param buffer The global buffer.
 -- @param marker_num A marker number in the range of `0` to `31`.
 -- @param pixmap `NULL`-terminated pixmap data.
 function marker_define_pixmap(buffer, marker_num, pixmap) end
 
 ---
--- Define a marker from RGBA data.
--- It has the width and height from `buffer.rgba_image_width` and
--- `buffer.rgba_image_height`.
+-- Defines RGBA image *pixels* for marker number *marker_num*, in the range of
+-- `0` to `31`.
+-- RGBA image markers use the `_SCINTILLA.constants.SC_MARK_RGBAIMAGE` marker
+-- symbol. The dimensions for *pixels*, `buffer.rgba_image_width` and
+-- `buffer.rgba_image_height`, must be already defined. *pixels* is a sequence
+-- of 4 byte pixel values (red, blue, green, and alpha) defining the image line
+-- by line starting at the top-left pixel.
 -- @param buffer The global buffer.
 -- @param marker_num A marker number in the range of `0` to `31`.
 -- @param pixels A sequence of 4 byte pixel values starting with the pixels for
@@ -1764,7 +1871,8 @@ function marker_define_pixmap(buffer, marker_num, pixmap) end
 function marker_define_rgba_image(buffer, marker_num, pixels) end
 
 ---
--- Delete a marker from a line.
+-- Deletes marker number *marker_num*, in the range of `0` to `31` or `-1` for
+-- all markers, from line number *line*.
 -- @param buffer The global buffer.
 -- @param line The line number.
 -- @param marker_num A marker number in the range of `0` to `31` or `-1` to
@@ -1772,44 +1880,47 @@ function marker_define_rgba_image(buffer, marker_num, pixels) end
 function marker_delete(buffer, line, marker_num) end
 
 ---
--- Delete all markers with a particular number from all lines.
+-- Deletes marker number *marker_num*, in the range of `0` to `31` or `-1` for
+-- all markers, from all lines in the buffer.
 -- @param buffer The global buffer.
 -- @param marker_num A marker number in the range of `0` to `31` or `-1` to
 --   delete all markers from the line.
 function marker_delete_all(buffer, marker_num) end
 
 ---
--- Delete a marker.
+-- Deletes the marker with handle *handle* returned by `buffer:marker_add()`.
 -- @param buffer The global buffer.
 -- @param handle The identifier of a marker returned by `buffer:marker_add()`.
 function marker_delete_handle(buffer, handle) end
 
 ---
--- Enable/disable highlight for current folding block (smallest one that
--- contains the caret)
+-- Highlights the margin fold markers for the current fold block if *enabled* is
+-- `true`.
 -- @param buffer The global buffer.
 -- @param enabled Whether to enable highlight.
 function marker_enable_highlight(buffer, enabled) end
 
 ---
--- Get a bit mask of all the markers set on a line.
--- Bit 0 is set if marker 0 is present, bit 1 for marker 1 and so on.
+-- Returns a bit-mask representing which markers are set line number *line*.
+-- Bit 0 is set if marker 0 is set, bit 1 for marker 1, etc.
 -- @param buffer The global buffer.
 -- @param line The line number.
 -- @return number.
 function marker_get(buffer, line) end
 
 ---
--- Retrieve the line number at which a particular marker is located.
--- Returns `-1` if it not found.
+-- Returns the line number the marker with handle *handle*, returned by
+-- `buffer:marker_add()`, is on, or `-1`.
 -- @param buffer The global buffer.
 -- @param handle The identifier of a marker returned by `buffer:marker_add()`.
 -- @return number
 function marker_line_from_handle(buffer, handle) end
 
 ---
--- Find the next line at or after start_line that includes a marker in mask.
--- Return `-1` when no more lines.
+-- Returns the first line number starting at line number *start_line* that has
+-- all of the markers represented by marker bit-mask *marker_mask* set on, or
+-- `-1`.
+-- Bit 0 is set if marker 0 is set, bit 1 for marker 1, etc., up to marker 31.
 -- @param buffer The global buffer.
 -- @param start_line The start line.
 -- @param marker_mask A mask of markers to find. Set bit 0 to find marker 0, bit
@@ -1818,7 +1929,10 @@ function marker_line_from_handle(buffer, handle) end
 function marker_next(buffer, start_line, marker_mask) end
 
 ---
--- Find the previous line before `start_line` that includes a marker in mask.
+-- Returns the last line number before or on line number *start_line* that has
+-- all of the markers represented by marker bit-mask *marker_mask* set on, or
+-- `-1`.
+-- Bit 0 is set if marker 0 is set, bit 1 for marker 1, etc., up to marker 31.
 -- @param buffer The global buffer.
 -- @param start_line The start line.
 -- @param marker_mask A mask of markers to find. Set bit 0 to find marker 0, bit
@@ -1827,180 +1941,176 @@ function marker_next(buffer, start_line, marker_mask) end
 function marker_previous(buffer, start_line, marker_mask) end
 
 ---
--- Return the symbol defined for marker_num with `buffer:marker_define()`.
+-- Returns the symbol defined for marker number *marker_num*, in the range of
+-- `0` to `31`, used in `buffer:marker_define()`,
+-- `buffer:marker_define_pixmap()`, or `buffer:marker_define_rgba_image()`.
 -- @param buffer The global buffer.
 -- @param marker_num A marker number in the range of `0` to `31`.
 -- @return number
 function marker_symbol_defined(buffer, marker_num) end
 
 ---
--- Move the caret inside current view if it is not there already.
--- Any selection is lost.
+-- Moves the current position to be visible inside the view if it is not
+-- already, removing any selections.
 -- @param buffer The global buffer.
 function move_caret_inside_view(buffer) end
 
 ---
--- Move the selected lines down one line, shifting the line below before the
--- selection.
--- The selection will be automatically extended to the beginning of the
--- selection's first line and the end of the seletion's last line. If nothing
--- was selected, the line the cursor is currently at will be selected.
+-- Moves the selected lines down one line.
 -- @param buffer The global buffer.
 function move_selected_lines_down(buffer) end
 
 ---
--- Move the selected lines up one line, shifting the line above after the
--- selection.
--- The selection will be automatically extended to the beginning of the
--- selection's first line and the end of the seletion's last line. If nothing
--- was selected, the line the cursor is currently at will be selected.
+-- Moves the selected lines up one line.
 -- @param buffer The global buffer.
 function move_selected_lines_up(buffer) end
 
 ---
--- Insert a new line, may use a CRLF, CR or LF depending on EOL mode.
+-- Inserts a new line character(s) at the current position depending on the end
+-- of line mode.
 -- @param buffer The global buffer.
 function new_line(buffer) end
 
 ---
--- Move caret one page down.
+-- Moves the caret one page down.
 -- @param buffer The global buffer.
 function page_down(buffer) end
 
 ---
--- Move caret one page down extending selection to new caret position.
+-- Moves the caret one page down, extending the selection to the new position.
 -- @param buffer The global buffer.
 function page_down_extend(buffer) end
 
 ---
--- Move caret one page down, extending rectangular selection to new caret
+-- Moves the caret one page down, extending the rectangular selection to the new
 -- position.
 -- @param buffer The global buffer.
 function page_down_rect_extend(buffer) end
 
 ---
--- Move caret one page up.
+-- Moves the caret one page up.
 -- @param buffer The global buffer.
 function page_up(buffer) end
 
 ---
--- Move caret one page up extending selection to new caret position.
+-- Moves the caret one page up, extending the selection to the new position.
 -- @param buffer The global buffer.
 function page_up_extend(buffer) end
 
 ---
--- Move caret one page up, extending rectangular selection to new caret
+-- Moves the caret one page up, extending the rectangular selection to the new
 -- position.
 -- @param buffer The global buffer.
 function page_up_rect_extend(buffer) end
 
 ---
--- Move caret one paragraph down (delimited by empty lines).
+-- Moves the caret one paragraph down.
+-- Paragraphs are surrounded by one or more blank lines.
 -- @param buffer The global buffer.
 function para_down(buffer) end
 
 ---
--- Move caret one paragraph down (delimited by empty lines) extending selection
--- to new caret position.
+-- Moves the caret one paragraph down, extending the selection to the new
+-- position.
+-- Paragraphs are surrounded by one or more blank lines.
 -- @param buffer The global buffer.
 function para_down_extend(buffer) end
 
 ---
--- Move caret one paragraph up (delimited by empty lines).
+-- Moves the caret one paragraph up.
+-- Paragraphs are surrounded by one or more blank lines.
 -- @param buffer The global buffer.
 function para_up(buffer) end
 
 ---
--- Move caret one paragraph up (delimited by empty lines) extending selection to
--- new caret position.
+-- Moves the caret one paragraph up, extending the selection to the new
+-- position.
+-- Paragraphs are surrounded by one or more blank lines.
 -- @param buffer The global buffer.
 function para_up_extend(buffer) end
 
 ---
--- Paste the contents of the clipboard into the document replacing the
--- selection.
+-- Pastes the contents of the clipboard into the buffer, replacing the selected
+-- text depending on `buffer.multi_paste`.
 -- @param buffer The global buffer.
 function paste(buffer) end
 
 ---
--- For private communication between an application and a known lexer.
--- @param buffer The global buffer.
--- @param operation An operation number.
--- @param data Number data.
-function private_lexer_call(buffer, operation, data) end
-
----
--- Retrieve the x value of the point in the window where a position is
--- displayed.
+-- Returns the x-coordinate in the view of position *pos*.
 -- @param buffer The global buffer.
 -- @param pos The position.
 -- @return number
 function point_x_from_position(buffer, pos) end
 
 ---
--- Retrieve the y value of the point in the window where a position is
--- displayed.
+-- Returns the y-coordinate in the view of position *pos*.
 -- @param buffer The global buffer.
 -- @param pos The position.
 -- @return number
 function point_y_from_position(buffer, pos) end
 
 ---
--- Given a valid document position, return the next position taking code page
--- into account. Maximum value returned is the last position in the document.
+-- Returns the position of the next character after position *pos*, taking code
+-- page into account, or `buffer.length - 1`.
 -- @param buffer The global buffer.
 -- @param pos The position.
 function position_after(buffer, pos) end
 
 ---
--- Given a valid document position, return the previous position taking code
--- page into account. Returns `0` if passed `0`.
+-- Returns the position of the previous character before position *pos*, taking
+-- code page into account, or `0`.
 -- @param buffer The global buffer.
 -- @param pos The position.
 -- @return number
 function position_before(buffer, pos) end
 
 ---
--- Retrieve the position at the start of a line.
--- If line is greater than the lines in the document, returns `-1`.
+-- Returns the position at the beginning of line number *line*.
+-- Returns `-1` if *line* is greater than `buffer.line_count`.
 -- @param buffer The global buffer.
 -- @param line The line.
 -- @return number
 function position_from_line(buffer, line) end
 
 ---
--- Find the position from a point within the window.
+-- Returns the position closest to view coordinates *x* and *y*, which may be
+-- in-between multi-byte characters.
 -- @param buffer The global buffer.
--- @param x The x-coordinate in the window.
--- @param y The y-coordinate in the window.
+-- @param x The x-coordinate in the view.
+-- @param y The y-coordinate in the view.
 -- @return number
 function position_from_point(buffer, x, y) end
 
 ---
--- Returns the position from a point within the window, but return `-1` if not
--- close to text.
+-- Returns the position closest to view coordinates *x* and *y*, which may be
+-- in-between multi-byte characters, or `-1` if the point is outside the window
+-- or not close to any text.
 -- @param buffer The global buffer.
--- @param x The x-coordinate in the window.
--- @param y The y-coordinate in the window.
+-- @param x The x-coordinate in the view.
+-- @param y The y-coordinate in the view.
 -- @return number
 function position_from_point_close(buffer, x, y) end
 
 ---
--- Redoes the next action on the undo history.
+-- Redoes the next undone action.
 -- @param buffer The global buffer.
 function redo(buffer) end
 
 ---
--- Register an XPM image for use in autocompletion lists.
+-- Registers XPM image *xpm_data* to type number *type* for use in
+-- autocompletion lists.
 -- @param buffer The global buffer.
 -- @param type Integer type to register the image with.
 -- @param xpm_data XPM data as is described for `buffer:marker_define_pixmap()`.
 function register_image(buffer, type, xpm_data) end
 
 ---
--- Register an RGBA image for use in autocompletion lists.
--- It has the width and height from `buffer.rgba_image_width` and
--- `buffer.rgba_image_height`.
+-- Registers RGBA image *pixels* to type number *type* for use in autocompletion
+-- lists.
+-- The dimensions for *pixels*, `buffer.rgba_image_width` and
+-- `buffer.rgba_image_height`, must be already defined. *pixels* is a sequence
+-- of 4 byte pixel values (red, blue, green, and alpha) defining the image line
+-- by line starting at the top-left pixel.
 -- @param buffer The global buffer.
 -- @param type Integer type to register the image with.
 -- @param pixels RGBA data as is described for
@@ -2008,75 +2118,75 @@ function register_image(buffer, type, xpm_data) end
 function register_rgba_image(buffer, type, pixels) end
 
 ---
--- Replace the selected text with the argument text.
--- The caret is positioned after the inserted text and the caret is scrolled
--- into view.
+-- Replaces the selected text with string *text*, scrolling the caret into view.
 -- @param buffer The global buffer.
 -- @param text The text.
 function replace_sel(buffer, text) end
 
 ---
--- Replace the target text with the argument text.
--- After replacement, the target range refers to the replacement text.
--- Returns the length of the replacement text.
+-- Replaces the text in the target range with string *text*, returning the
+-- length of *text*.
+-- The recommended way to delete text in the buffer is to set the target to the
+-- text to be removed, and to call this function with an empty string.
 -- @param buffer The global buffer.
 -- @param text The text (can contain null bytes).
 -- @return number
 function replace_target(buffer, text) end
 
 ---
--- Replace the target text with the argument text after `\d` processing.
--- Looks for `\d` where `d` is between `1` and `9` and replaces these with the
--- strings matched in the last search operation which were surrounded by `\(`
--- and `\)`. Returns the length of the replacement text including any change
--- caused by processing the `\d` patterns.
+-- Replaces the text in the target range with string *text* after replacing any
+-- "\d" sequences, where `d` is a number in the range of `1` to `9`, with the
+-- tag match values from the regular expression or the entire match for "\0",
+-- returning the length of the replacement text.
 -- @param buffer The global buffer.
 -- @param text The text (can contain null bytes).
 -- @return number
 function replace_target_re(buffer, text) end
 
 ---
--- Set the main selection to the next selection.
+-- Sets the next additional selection to be the main selection.
 -- @param buffer The global buffer.
 function rotate_selection(buffer) end
 
 ---
--- Ensure the caret is visible.
+-- Scrolls the current position into view based on the policies set with
+-- `buffer:set_x_caret_policy()` and `buffer:set_y_caret_policy()`.
 -- @param buffer The global buffer.
+-- @see set_x_caret_policy
+-- @see set_y_caret_policy
 function scroll_caret(buffer) end
 
 ---
--- Scroll to end of document.
+-- Scroll to the end of the buffer without moving the caret.
 -- @param buffer The global buffer.
 function scroll_to_end(buffer) end
 
 ---
--- Scroll to start of document.
+-- Scroll to the beginning of the buffer without moving the caret.
 -- @param buffer The global buffer.
 function scroll_to_start(buffer) end
 
 ---
--- Sets the current caret position to be the search anchor.
--- Always call this before calling either of `buffer:search_next()` or
--- `buffer:search_prev()`.
+-- Sets the current position to anchor subsequent searches with
+-- `buffer:search_next()` and `buffer:search_prev()`.
 -- @param buffer The global buffer.
 function search_anchor(buffer) end
 
 ---
--- Search for a counted string in the target and set the target to the found
--- range.
--- Returns length of range or `-1` for failure in which case target is not
--- moved.
+-- Searches for the first occurrence of string *text* in the target range
+-- bounded by `buffer.target_start` and `buffer.target_end` using search flags
+-- `buffer.search_flags` and, if found, sets the new target range to that
+-- occurrence, returning its position or `-1` otherwise.
 -- @param buffer The global buffer.
 -- @param text The text (can contain null bytes).
 -- @return number
 function search_in_target(buffer, text) end
 
 ---
--- Find some text starting at the search anchor.
--- The return value is `-1` if nothing is found, otherwise the return value is
--- the start position of the matching text. The selection is updated to show the
--- matched text, but is not scrolled into view.
+-- 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`.
+-- Selected text is not scrolled into view.
 -- @param buffer The global buffer.
 -- @param flags Search flags. See `buffer.search_flags`.
 -- @param text The text.
@@ -2085,10 +2195,9 @@ function search_in_target(buffer, text) end
 function search_next(buffer, flags, text) end
 
 ---
--- Find some text starting at the search anchor and moving backwards.
--- The return value is `-1` if nothing is found, otherwise the return value is
--- the start position of the matching text. The selection is updated to show the
--- matched text, but is not scrolled into view.
+-- 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`.
 -- @param buffer The global buffer.
 -- @param flags Search flags. See `buffer.search_flags`.
 -- @param text The text.
@@ -2097,75 +2206,75 @@ function search_next(buffer, flags, text) end
 function search_prev(buffer, flags, text) end
 
 ---
--- Select all the text in the document.
--- The current position is not scrolled into view.
+-- Selects all of the text in the buffer without scrolling the view.
 -- @param buffer The global buffer.
 function select_all(buffer) end
 
 ---
--- Duplicate the selection.
--- If selection empty duplicate the line containing the caret.
+-- Duplicates the selected text or the current line.
 -- @param buffer The global buffer.
 function selection_duplicate(buffer) end
 
 ---
--- Reset the set of characters for whitespace and word characters to the
--- defaults.
--- This sets whitespace to space, tab and other characters with codes less than
--- 0x20, with word characters set to alphanumeric and '_'.
+-- Resets the set of whitespace and word characters to their default characters.
 -- @param buffer The global buffer.
+-- @see whitespace_chars
+-- @see word_chars
 function set_chars_default(buffer) end
 
 ---
--- Set caret to a position, while removing any existing selection.
--- The caret is not scrolled into view.
+-- Sets the current position to position *pos* without scrolling the view,
+-- removing any selections.
 -- @param buffer The buffer
 -- @param pos The position to move to.
 function set_empty_selection(buffer, pos) end
 
 ---
--- Set the colors used as a chequerboard pattern in the fold margin.
+-- Overrides the default color of the fold margin with *color*, in "0xBBGGRR"
+-- format, if *use_setting* is `true`.
 -- @param buffer The global buffer.
 -- @param use_setting Enable color change.
 -- @param color A color in "0xBBGGRR" format.
 function set_fold_margin_colour(buffer, use_setting, color) end
 
 ---
--- Set the colors used as a checkerboard pattern in the fold margin.
+-- Overrides the default highlight color of the fold margin with *color*, in
+-- "0xBBGGRR" format, if *use_setting* is `true`.
 -- @param buffer The global buffer.
 -- @param use_setting Enable color change.
 -- @param color A color in "0xBBGGRR" format.
 function set_fold_margin_hi_colour(buffer, use_setting, color) end
 
 ---
--- Set a back color for active hotspots.
+-- Overrides the default background color of active hotspots with *color*, in
+-- "0xBBGGRR" format, if *use_setting* is `true`.
 -- @param buffer The global buffer.
 -- @param use_setting Enable the color change.
 -- @param color A color in "0xBBGGRR" format.
 function set_hotspot_active_back(buffer, use_setting, color) end
 
 ---
--- Set a fore color for active hotspots.
+-- Overrides the default foreground color of active hotspots with *color*, in
+-- "0xBBGGRR" format, if *use_setting* is `true`.
 -- @param buffer The global buffer.
 -- @param use_setting Enable the color change.
 -- @param color A color in "0xBBGGRR" format.
 function set_hotspot_active_fore(buffer, use_setting, color) end
 
 ---
--- Set the length of the utf8 argument for calling `buffer:encoded_from_utf8()`.
+-- Sets the length of *string* in `buffer:encoded_from_utf8()` to *bytes*.
 -- @param buffer The global buffer.
 -- @param bytes Bytes or `-1` for measuring to first null byte.
 function set_length_for_encode(buffer, bytes) end
 
 ---
--- Remember the current position in the undo history as the position at which
--- the document was saved.
+-- Tells Scintilla the buffer has no unsaved changes.
 -- @param buffer The global buffer.
 function set_save_point(buffer) end
 
 ---
--- Select a range of text.
--- The caret is scrolled into view after this operation.
+-- Selects the range of text from *start_pos* to *end_pos* in the buffer,
+-- scrolling the selected text into view.
 -- @param buffer The global buffer.
 -- @param start_pos Start position. If negative, it means the end of the
 --   document.
@@ -2174,45 +2283,48 @@ function set_save_point(buffer) end
 function set_sel(buffer, start_pos, end_pos) end
 
 ---
--- Set the background color of the main and additional selections and whether to
--- use this setting.
+-- Overrides the default background color of all selected text with *color*, in
+-- "0xBBGGRR" format, if *use_setting* is `true`.
 -- @param buffer The global buffer.
 -- @param use_setting Enable color change.
 -- @param color A color in "0xBBGGRR" format.
 function set_sel_back(buffer, use_setting, color) end
 
 ---
--- Set the foreground color of the main and additional selections and whether
--- to use this setting.
+-- Overrides the default foreground color of all selected text with *color*, in
+-- "0xBBGGRR" format, if *use_setting* is `true`.
 -- @param buffer The global buffer.
 -- @param use_setting Enable color change.
 -- @param color A color in "0xBBGGRR" format.
 function set_sel_fore(buffer, use_setting, color) end
 
 ---
--- Set a simple selection from anchor to caret.
+-- Selects the range of text from *anchor* to *caret* in the buffer, removing
+-- all other selections.
 -- @param buffer The global buffer.
 -- @param caret The caret.
 -- @param anchor The anchor.
 function set_selection(buffer, caret, anchor) end
 
 ---
--- Change style from current styling position for length characters to a style
--- and move the current styling position to after this newly styled segment.
+-- Sets 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.
 -- @param length The length to style.
 -- @param style The style number to set.
 function set_styling(buffer, length, style) end
 
 ---
--- Replace the contents of the document with the argument text.
+-- Replaces all of the text in the buffer with string *text*.
 -- @param buffer The global buffer.
 -- @param text The text.
 function set_text(buffer, text) end
 
 ---
--- Set the way the display area is determined when a particular line is to be
--- moved to by `buffer:goto_line()`, etc.
+-- Sets the visible policy bit-mask *visible_policy* for displaying lines using
+-- `buffer:ensure_visible_enforce_policy()` to *visible_slop* number of lines
+-- from the bottom of the view.
 -- It is similar in operation to `buffer:set_y_caret_policy()`.
 -- @param buffer The global buffer.
 -- @param visible_policy A combination of `_SCINTILLA.constants.VISIBLE_SLOP`
@@ -2221,15 +2333,16 @@ function set_text(buffer, text) end
 function set_visible_policy(buffer, visible_policy, visible_slop) end
 
 ---
--- Set the background color of all whitespace and whether to use this setting.
+-- Overrides the background color of whitespace with *color*, in "0xBBGGRR"
+-- format, if *use_setting* is `true`.
 -- @param buffer The global buffer.
 -- @param use_setting Enable color change.
 -- @param color A color in "0xBBGGRR" format.
 function set_whitespace_back(buffer, use_setting, color) end
 
 ---
--- Set the foreground color of all whitespace and whether to use this setting.
--- @param buffer The global buffer.
+-- Overrides the foreground color of whitespace with *color*, in "0xBBGGRR"
+-- format, if *use_setting* is `true`.
 -- @param use_setting Enable color change.
 -- @param color A color in "0xBBGGRR" format.
 function set_whitespace_fore(buffer, use_setting, color) end
@@ -2256,8 +2369,8 @@ function set_x_caret_policy(buffer, caret_policy, caret_slop) end
 function set_y_caret_policy(buffer, caret_policy, caret_slop) end
 
 ---
--- Make a range of lines visible.
--- This has no effect on fold levels or fold flags. `start_line` can not be
+-- Shows the range of lines from line number *start_line* to *end_line*.
+-- This has no effect on fold levels or fold flags and the first line cannot be
 -- hidden.
 -- @param buffer The global buffer.
 -- @param start_line The start line.
@@ -2265,88 +2378,81 @@ function set_y_caret_policy(buffer, caret_policy, caret_slop) end
 function show_lines(buffer, start_line, end_line) end
 
 ---
--- Start notifying the container of all key presses and commands.
--- @param buffer The global buffer.
-function start_record(buffer) end
-
----
--- Set the current styling position to pos and the styling mask to mask.
--- The styling mask can be used to protect some bits in each styling byte from
--- modification.
+-- Begin styling at position *position* with the 8-bit styling bit-mask *mask*
+-- that determines which style bits can be set with `buffer:set_styling()`.
 -- @param buffer The global buffer.
 -- @param position The styling position.
 -- @param mask The bit mask of the style bytes that can be set.
+-- @usage buffer:start_styling(0, 0xFF)
 function start_styling(buffer, position, mask) end
 
 ---
--- Stop notifying the container of all key presses and commands.
--- @param buffer The global buffer.
-function stop_record(buffer) end
-
----
--- Move caret to bottom of page, or one page down if already at bottom of page.
+-- Moves the caret to the bottom of the page, or if already there, one page
+-- down.
 -- @param buffer The global buffer.
 function stuttered_page_down(buffer) end
 
 ---
--- Move caret to bottom of page, or one page down if already at bottom of page,
--- extending selection to new caret position.
+-- Like `buffer:stuttered_page_down()`, but extends the selection to the new
+-- position.
 -- @param buffer The global buffer.
 function stuttered_page_down_extend(buffer) end
 
 ---
--- Move caret to top of page, or one page up if already at top of page.
+-- Moves the caret to the top of the page, or if already there, one page up.
 -- @param buffer The global buffer.
 function stuttered_page_up(buffer) end
 
 ---
--- Move caret to top of page, or one page up if already at top of page,
--- extending selection to new caret position.
+-- Like `buffer:stuttered_page_up()`, but extends the selection to the new
+-- position.
 -- @param buffer The global buffer.
 function stuttered_page_up_extend(buffer) end
 
 ---
--- Clear all the styles and make equivalent to the global default style.
+-- Sets all styles to have the same properties as
+-- `_SCINTILLA.constants.STYLE_DEFAULT`.
 -- @param buffer The global buffer.
 function style_clear_all(buffer) end
 
 ---
--- Reset the default style to its state at startup.
+-- Resets `_SCINTILLA.constants.STYLE_DEFAULT` to its initial state.
 -- @param buffer The global buffer.
 function style_reset_default(buffer) end
 
 ---
--- Swap that caret and anchor of the main selection.
+-- Swaps the anchor and caret positions of the main selection.
 -- @param buffer The global buffer.
 function swap_main_anchor_caret(buffer) end
 
 ---
--- If selection is empty or all on one line replace the selection with a tab
--- character, or if more than one line selected, indent the lines.
+-- Indents the selected lines, replaces the selected text on a line with a Tab
+-- character ("\t"), or inserts a Tab character at the current position.
 -- @param buffer The global buffer.
 function tab(buffer) end
 
 ---
--- Returns the target converted to UTF8.
+-- Returns the result of the text in the target range converted from the
+-- buffer's code page into UTF-8.
 -- @param buffer The global buffer.
 function target_as_utf8(buffer) end
 
 ---
--- Make the target range start and end be the same as the selection range start
--- and end.
+-- Sets the beginning and end positions of the target range to be the beginning
+-- and end positions of the main selection.
 -- @param buffer The global buffer.
 function target_from_selection(buffer) end
 
 ---
--- Retrieve the height of a particular line of text in pixels.
+-- Returns the height in pixels of line number *line*.
 -- @param buffer The global buffer.
 -- @param line The line number.
 -- @return number
 function text_height(buffer, line) end
 
 ---
--- Measure the pixel width of some text in a particular style.
--- Does not handle tab or control characters.
+-- Returns the width in pixels of string *text* styled with style number
+-- *style_num*, in the range of `0` to `255`.
 -- @param buffer The global buffer.
 -- @param style_num The style number between `0` and `255`.
 -- @param text The text.
@@ -2354,36 +2460,37 @@ function text_height(buffer, line) end
 function text_width(buffer, style_num, text) end
 
 ---
--- Switch between sticky and non-sticky: meant to be bound to a key.
--- See `buffer.caret_sticky`.
+-- Cycles between caret sticky option settings
+-- `_SCINTILLA.constants.SC_CARETSTICKY_ON`,
+-- `_SCINTILLA.constants.SC_CARETSTICKY_WHITESPACE`, and
+-- `_SCINTILLA.constants.SC_CARETSTICKY_OFF`.
 -- @param buffer The global buffer.
+-- @see caret_sticky
 function toggle_caret_sticky(buffer) end
 
 ---
--- Switch a header line between expanded and contracted.
+-- Toggles the fold state of a fold header line between expanded, where all
+-- of its child lines are displayed, and contracted, where all of its child
+-- lines are hidden.
 -- @param buffer The global buffer.
 -- @param line The line number.
 function toggle_fold(buffer, line) end
 
 ---
--- Undo one action in the undo history.
+-- Undoes the most recent action.
 -- @param buffer The global buffer.
 function undo(buffer) end
 
 ---
--- Transform the selection to upper case.
+-- Converts the selected text to upper case letters.
 -- @param buffer The global buffer.
 function upper_case(buffer) end
 
 ---
--- Sets whether a pop up menu is displayed automatically when the user presses
--- the wrong mouse button.
--- @param buffer The global buffer.
--- @param allow_popup Allow popup menu.
-function use_pop_up(buffer, allow_popup) end
-
----
--- Display a list of strings and send notification when user chooses one.
+-- Displays a list from *item_list*, a sorted string whose items are delimited
+-- by `buffer.auto_c_separator` characters, using the list identifier number
+-- *list_type* which is greater than zero and sent in a `USER_LIST_SELECTION`
+-- event after selecting an item.
 -- @param buffer The global buffer.
 -- @param list_type A list identifier number greater than zero.
 -- @param item_list List of words separated by separator characters (initially
@@ -2392,63 +2499,65 @@ function use_pop_up(buffer, allow_popup) end
 function user_list_show(buffer, list_type, item_list) end
 
 ---
--- Move caret to before first visible character on line.
--- If already there move to first character on line.
+-- Moves the caret to the first visible character on the current line, or if
+-- already there, to the beginning of the current line.
 -- @param buffer The global buffer.
 function vc_home(buffer) end
 
 ---
--- Move caret to before first visible character on display line.
--- If already there move to first character on display line.
+-- Moves the caret to the first visible character on the current wrapped line,
+-- or if already there, to the beginning of the current wrapped line.
 -- @param buffer The global buffer.
 function vc_home_display(buffer) end
 
 ---
--- Like `buffer:vc_home_display()` but extending selection to new caret
+-- Like `buffer:vc_home_display()`, but extends the selection to the new
 -- position.
 -- @param buffer The global buffer.
 function vc_home_display_extend(buffer) end
 
 ---
--- Like `buffer:vc_home()` but extending selection to new caret position.
+-- Like `buffer:vc_home()`, but extends the selection to the new position.
 -- @param buffer The global buffer.
 function vc_home_extend(buffer) end
 
 ---
--- Move caret to before first visible character on line.
--- If already there move to first character on line. In either case, extend
--- rectangular selection to new caret position.
+-- Like `buffer:vc_home()`, but extends the rectangular selection to the new
+-- position.
 -- @param buffer The global buffer.
 function vc_home_rect_extend(buffer) end
 
 ---
--- Move caret to before first visible character on display line when word-wrap
--- is enabled.
--- If already there, go to first character on display line.
+-- Moves the caret to the first visible character on the wrapped line, or if
+-- already there, to the beginning of the actual line.
 -- @param buffer The global buffer.
 function vc_home_wrap(buffer) end
 
 ---
--- Like `buffer:vc_home_wrap()` but extending selection to new caret position.
+-- Like `buffer:vc_home_wrap()`, but extends the selection to the new position.
 -- @param buffer The global buffer.
 function vc_home_wrap_extend(buffer) end
 
 ---
--- Center current line in window.
+-- Centers current line in the view.
 -- @param buffer The global buffer.
 function vertical_centre_caret(buffer) end
 
 ---
--- Find the display line of a document line taking hidden lines into account.
--- If there is folding and line is outside the range of lines in the document,
--- the return value is `-1`.
+-- Returns the displayed line number of actual line number *line*, taking hidden
+-- lines into account, or `-1` if *line* is outside the range of lines in the
+-- buffer.
+-- Lines can occupy more than one display line if they wrap.
 -- @param buffer The global buffer.
 -- @param line The line number.
 -- @return number
 function visible_from_doc_line(buffer, line) end
 
 ---
--- Get position of end of word.
+-- 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.
 -- @param buffer The global buffer.
 -- @param pos The position.
 -- @param only_word_chars If `true`, stops searching at the first non-word
@@ -2459,71 +2568,87 @@ function visible_from_doc_line(buffer, line) end
 function word_end_position(buffer, pos, only_word_chars) end
 
 ---
--- Move caret left one word.
+-- Moves the caret left one word.
+-- `buffer.word_chars` contains word characters.
 -- @param buffer The global buffer.
 function word_left(buffer) end
 
 ---
--- Move caret left one word, position cursor at end of word.
+-- Moves the caret left one word, positioning the current position at the end of
+-- the previous word.
+-- `buffer.word_chars` contains word characters.
 -- @param buffer The global buffer.
 function word_left_end(buffer) end
 
 ---
--- Move caret left one word, position cursor at end of word, extending selection
--- to new caret position.
+-- Like `buffer:word_left_end()`, but extends the selection to the new position.
 -- @param buffer The global buffer.
 function word_left_end_extend(buffer) end
 
 ---
--- Move caret left one word extending selection to new caret position.
+-- Moves the caret left one word, extending the selection to the new position.
+-- `buffer.word_chars` contains word characters.
 -- @param buffer The global buffer.
 function word_left_extend(buffer) end
 
 ---
--- Move to the previous change in capitalisation or underscores.
+-- Moves to the previous underscore or change in capitalization within the
+-- current word.
+-- `buffer.word_chars` contains word characters.
 -- @param buffer The global buffer.
 function word_part_left(buffer) end
 
 ---
--- Move to the previous change in capitalisation or underscores extending
--- selection to new caret position.
+-- Moves to the previous underscore or change in capitalization within the
+-- current word, extending the selection to the new position.
+-- `buffer.word_chars` contains word characters.
 -- @param buffer The global buffer.
 function word_part_left_extend(buffer) end
 
 ---
--- Move to the next change in capitalisation or underscores.
+-- Moves to the next underscore or change in capitalization within the current
+-- word.
+-- `buffer.word_chars` contains word characters.
 -- @param buffer The global buffer.
 function word_part_right(buffer) end
 
 ---
--- Move to the next change in capitalisation or underscores extending selection
--- to new caret position.
+-- Moves to the next underscore or change in capitalization within the current
+-- word, extending the selection to the new position.
+-- `buffer.word_chars` contains word characters.
 -- @param buffer The global buffer.
 function word_part_right_extend(buffer) end
 
 ---
--- Move caret right one word.
+-- Moves the caret right one word.
+-- `buffer.word_chars` contains word characters.
 -- @param buffer The global buffer.
 function word_right(buffer) end
 
 ---
--- Move caret right one word, position cursor at end of word.
+-- Moves the caret right one word, positioning the cursor at the end of the
+-- current word.
+-- `buffer.word_chars` contains word characters.
 -- @param buffer The global buffer.
 function word_right_end(buffer) end
 
 ---
--- Move caret right one word, position cursor at end of word, extending
--- selection to new caret position.
+-- Like `buffer:word_right_end()`, but extends the selection to the new
+-- position.
 -- @param buffer The global buffer.
 function word_right_end_extend(buffer) end
 
 ---
--- Move caret right one word extending selection to new caret position.
+-- Moves the caret right one word, extending the selection to the new position.
+-- `buffer.word_chars` contains word characters.
 -- @param buffer The global buffer.
 function word_right_extend(buffer) end
 
 ---
--- Get position of start of word.
+-- 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.
 -- @param buffer The global buffer.
 -- @param pos The position.
 -- @param only_word_chars If `true`, stops searching at the first non-word
@@ -2534,58 +2659,56 @@ function word_right_extend(buffer) end
 function word_start_position(buffer, pos, only_word_chars) end
 
 ---
--- Returns the number of display lines needed to wrap a document line.
+-- Returns the number of wrapped lines needed to display line number *line*.
 -- @param buffer The global buffer.
 -- @param line The line number.
 -- @return number
 function wrap_count(buffer, line) end
 
 ---
--- Magnify the displayed text by increasing the sizes by 1 point if the current
--- zoom factor is less than 20 points.
+-- Increases the size of all fonts by one point, up to 20.
 -- @param buffer The global buffer.
 function zoom_in(buffer) end
 
 ---
--- Make the displayed text smaller by decreasing the sizes by 1 point if the
--- current zoom factor is greater than -10 points.
+-- Decreases the size of all fonts by one point, down to -10.
 -- @param buffer The global buffer.
 function zoom_out(buffer) end
 
 -- External functions.
 
 ---
--- Checks whether the given buffer is the global one.
--- If not, throws an error indicating so. It is necessary to call this at the
--- top of all buffer functions to avoid unexpected behavior since most buffer
--- functions operate on `_G.buffer`, which is not necessarily the given one.
+-- Ensures the buffer is the global one, `_G.buffer`, throwing an error
+-- otherwise.
+-- This function must be called in all buffer functions because only the global
+-- buffer can be worked with.
 -- @param buffer The buffer to check.
 -- @see _G._G.buffer
 function check_global(buffer) end
 
 ---
--- Deletes the current buffer.
--- WARNING: this function should NOT be called via scripts. Use `buffer:close()`
--- instead, which prompts for confirmation if necessary. Emits a
+-- Deletes the buffer.
+-- **Do not call this function.** Call `buffer:close()` instead. Emits a
 -- `BUFFER_DELETED` event.
 -- @param buffer The global buffer.
 -- @see events.BUFFER_DELETED
 function delete(buffer) end
 
 ---
--- Gets a range of text from the current buffer.
+-- Returns the range of text from *start_pos* to *end_pos* in the buffer.
 -- @param buffer The global buffer.
 -- @param start_pos The beginning position of the range of text to get.
 -- @param end_pos The end position of the range of text to get.
 function text_range(buffer, start_pos, end_pos) end
 
 ---
--- Reloads the file in a given buffer.
+-- Reloads the file in the buffer.
 -- @param buffer The global buffer.
 function reload(buffer) end
 
 ---
--- Sets the encoding for the buffer, converting its contents in the process.
+-- Sets the encoding for the buffer to *encoding*, converting its contents from
+-- the old encoding to the new one.
 -- @param buffer The global buffer.
 -- @param encoding The encoding to set. Valid encodings are ones that GNU iconv
 --   accepts.
@@ -2593,14 +2716,14 @@ function reload(buffer) end
 function set_encoding(buffer, encoding) end
 
 ---
--- Saves the current buffer to a file.
+-- Saves the buffer to the file.
 -- Emits `FILE_BEFORE_SAVE` and `FILE_AFTER_SAVE` events.
 -- @param buffer The global buffer.
 -- @see _G.events
 function save(buffer) end
 
 ---
--- Saves the current buffer to a file different than its filename property.
+-- Saves the buffer to the *utf8_filename* or user-specified filename.
 -- Emits a `FILE_SAVED_AS` event.
 -- @param buffer The global buffer.
 -- @param utf8_filename The new filepath to save the buffer to. Must be UTF-8
@@ -2609,46 +2732,50 @@ function save(buffer) end
 function save_as(buffer, utf8_filename) end
 
 ---
--- Closes the current buffer.
+-- Closes the buffer, prompting the user to continue if there are unsaved
+-- changes, and returns `true` if the buffer was closed.
 -- @param buffer The global buffer.
--- If the buffer is dirty, the user is prompted to continue. The buffer is not
--- saved automatically. It must be done manually.
 -- @return `true` if the buffer was closed; `nil` otherwise.
 function close(buffer) end
 
 ---
--- Replacement for `buffer.lexer_language =`.
--- 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.
--- Loads the language-specific module if it exists.
--- This function is added by `_M.textadept.mime_types`.
+-- Sets the name of the lexer used by the buffer to *lang*, loading its
+-- language-specific module if the module exists.
 -- @param buffer The global buffer.
 -- @param lang The string language to set.
 -- @usage buffer.set_lexer(buffer, 'language_name')
 function set_lexer(buffer, lang) end
 
 ---
--- Replacement for `buffer.lexer_language`.
+-- Returns the name of the lexer used by the buffer, or the name of the lexer at
+-- the current position in a multiple-language lexer if *current* is `true`.
 -- @param buffer The global buffer.
 -- @param current Whether to get the lexer at the current caret position in
 --   multi-language lexers. The default is `false` and returns the parent lexer.
 function get_lexer(buffer, current) end
 
 ---
--- Returns the name of the style associated with a style number.
+-- Returns the name of style number *style_num*, in the range of `0` to `255`.
 -- @param buffer The global buffer.
 -- @param style_num A style number from `0` to `255`.
 -- @see buffer.style_at
 function get_style_name(buffer, style_num) end
 
 -- Unused Fields.
+--   * status
+--   * mouse_down_captures
+--   * focus
 --   * use_palette
+--   * font_quality
+--   * keys_unicode
 --   * doc_pointer
 --   * mod_event_mask
 --   * paste_convert_endings
+--   * direct_function
+--   * direct_pointer
 --   * character_pointer
 --   * get_range_pointer
+--   * field gap_position
 --   * identifier
 --   * key_words
 --   * technology
@@ -2662,6 +2789,9 @@ function get_style_name(buffer, style_num) end
 --   * find_text
 --   * format_range
 --   * null
+--   * use_pop_up
+--   * start_record
+--   * stop_record
 --   * create_document
 --   * add_ref_document
 --   * release_document
@@ -2679,3 +2809,4 @@ function get_style_name(buffer, style_num) end
 --   * describe_property
 --   * describe_key_word_sets
 --   * create_loader
+--   * private_lexer_call
diff --git a/core/.iconv.luadoc b/core/.iconv.luadoc
index 78616a30..b21f6c5a 100644
--- a/core/.iconv.luadoc
+++ b/core/.iconv.luadoc
@@ -6,8 +6,30 @@
 module('string')
 
 ---
--- Converts a string from one character set to another using iconv.
--- Valid character sets are [GNU iconv's character sets][].
+-- Converts string *text* from character set *from* to character set *to* using
+-- iconv.
+-- Valid character sets are [GNU iconv's character sets][] and include:
+--
+--   * European: ASCII, ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16}, KOI8-R, KOI8-U,
+--     KOI8-RU, CP{1250,1251,1252,1253,1254,1257}, CP{850,866,1131},
+--     Mac{Roman,CentralEurope,Iceland,Croatian,Romania},
+--     Mac{Cyrillic,Ukraine,Greek,Turkish}, Macintosh.
+--   * Semitic: ISO-8859-{6,8}, CP{1255,1256}, CP862, Mac{Hebrew,Arabic}.
+--   * Japanese: EUC-JP, SHIFT_JIS, CP932, ISO-2022-JP, ISO-2022-JP-2,
+--     ISO-2022-JP-1.
+--   * Chinese: EUC-CN, HZ, GBK, CP936, GB18030, EUC-TW, BIG5, CP950,
+--     BIG5-HKSCS, BIG5-HKSCS:2004, BIG5-HKSCS:2001, BIG5-HKSCS:1999,
+--     ISO-2022-CN, ISO-2022-CN-EXT.
+--   * Korean: EUC-KR, CP949, ISO-2022-KR, JOHAB.
+--   * Armenian: ARMSCII-8.
+--   * Georgian: Georgian-Academy, Georgian-PS.
+--   * Tajik: KOI8-T.
+--   * Kazakh: PT154, RK1048.
+--   * Thai: ISO-8859-11, TIS-620, CP874, MacThai.
+--   * Laotian: MuleLao-1, CP1133.
+--   * Vietnamese: VISCII, TCVN, CP1258.
+--   * Unicode: UTF-8, UCS-2, UCS-2BE, UCS-2LE, UCS-4, UCS-4BE, UCS-4LE, UTF-16,
+--     UTF-16BE, UTF-16LE, UTF-32, UTF-32BE, UTF-32LE, UTF-7, C99, JAVA.
 --
 -- [GNU iconv's character sets]: http://www.gnu.org/software/libiconv/
 -- @param text The text to convert.
diff --git a/core/.view.luadoc b/core/.view.luadoc
index 6913baa6..269c818d 100644
--- a/core/.view.luadoc
+++ b/core/.view.luadoc
@@ -15,29 +15,34 @@ module('view')
 local buffer
 
 ---
--- Splits the given view vertically or horizontally and focuses the new view.
+-- Splits the view into top and bottom views, unless *vertical* is `true`,
+-- focuses the new view, and returns both the old and new views.
+-- If *vertical* is `false`, splits the view vertically into left and
+-- right views.
 -- Emits a `VIEW_NEW` event.
 -- @param view The view to split.
--- @param vertical Flag indicating a vertical split. The default value is
---   `false` for horizontal.
+-- @param vertical Optional flag indicating whether or not to split the view
+--   vertically. The default value is `false` for horizontal.
 -- @return old view and new view.
 -- @see events.VIEW_NEW
 function split(view, vertical) end
 
 ---
--- Unsplits the given view if possible.
+-- Unsplits the view if possible, returning `true` on success.
 -- @param view The view to unsplit.
 -- @return boolean if the view was unsplit or not.
 function unsplit(view) end
 
 ---
--- Goes to the specified buffer in the given view.
+-- Goes to buffer number *n* in the view.
+-- If *relative* is `true`, *n* is an index relative to the index of the current
+-- buffer in `_G._BUFFERS` instead of an absolute index.
 -- Emits `BUFFER_BEFORE_SWITCH` and `BUFFER_AFTER_SWITCH` events.
 -- @param view The view to switch buffers in.
 -- @param n A relative or absolute buffer index in `_G._BUFFERS`. An absolute
 --   index of `-1` goes to the last buffer.
--- @param relative Flag indicating if `n` is a relative index or not. The
---   default value is `false`.
+-- @param relative Optional flag indicating whether *n* is a relative or
+--   absolute index. The default value is `false` for an absolute index.
 -- @see _G._G._BUFFERS
 -- @see events.BUFFER_BEFORE_SWITCH
 -- @see events.BUFFER_AFTER_SWITCH
diff --git a/core/args.lua b/core/args.lua
index 1a410ba4..b7ddde8d 100644
--- a/core/args.lua
+++ b/core/args.lua
@@ -20,23 +20,26 @@ local arg = arg
 local switches = {}
 
 ---
--- Registers a command line switch.
--- @param switch1 String switch (short version).
--- @param switch2 String switch (long version).
+-- Registers a command line switch with short and long versions *short* and
+-- *long*, respectively. *narg* is the number of arguments the switch accepts,
+-- *f* is the function called when the switch is tripped, and *description* is
+-- the switch's description when displaying help.
+-- @param short String short version of the switch.
+-- @param long String long version of the switch.
 -- @param narg The number of expected parameters for the switch.
 -- @param f The Lua function to run when the switch is tripped.
 -- @param description Description of the switch for command line help.
 -- @name register
-function M.register(switch1, switch2, narg, f, description)
+function M.register(short, long, narg, f, description)
   local t = {f, narg, description}
-  switches[switch1], switches[switch2] = t, t
+  switches[short], switches[long] = t, t
 end
 
 ---
--- Processes command line arguments.
--- Add command line switches with `args.register()`. Any unrecognized arguments
--- are treated as filepaths and opened.
--- Emits an `'arg_none'` event when no args are present.
+-- Processes command line argument table *arg*, handling switches previously
+-- defined using `args.register()` and treating unrecognized arguments as
+-- filenames to open.
+-- Emits an `'arg_none'` event when no arguments are present.
 -- @param arg Argument table.
 -- @see register
 -- @see events
diff --git a/core/events.lua b/core/events.lua
index 9139a30a..46ee8f6c 100644
--- a/core/events.lua
+++ b/core/events.lua
@@ -27,241 +27,233 @@ local M = {}
 --   Called when Mac OSX tells Textadept to open a document.
 --   Arguments:
 --
---   * `uri`: The URI to open encoded in UTF-8.
+--   * _`uri`_: The UTF-8-encoded URI to open.
 -- @field AUTO_C_CHAR_DELETED (string)
---   Called when the user deleted a character while the autocompletion list was
---   active.
+--   Called when deleting a character while the autocompletion list is active.
 -- @field AUTO_C_RELEASE (string)
---   Called when the user has cancelled the autocompletion list.
+--   Called when canceling the autocompletion list.
 -- @field AUTO_C_SELECTION (string)
---   Called when the user has selected an item in an autocompletion list and
---   before the selection is inserted.
+--   Called when selecting an item in the autocompletion list and before
+--   inserting the selection.
 --   Automatic insertion can be cancelled by calling
 --   [`buffer:auto_c_cancel()`][] before returning from the event handler.
 --   Arguments:
 --
---   * `text`: The text of the selection.
---   * `position`: The start position of the word being completed.
+--   * _`text`_: The text of the selection.
+--   * _`position`_: The position in the buffer of the beginning of the
+--     autocompleted word.
 -- @field BUFFER_AFTER_SWITCH (string)
---   Called right after a buffer is switched to.
---   This is emitted by [`view:goto_buffer()`][].
+--   Called right after switching to another buffer.
+--   Emitted by [`view:goto_buffer()`][].
 -- @field BUFFER_BEFORE_SWITCH (string)
---   Called right before another buffer is switched to.
---   This is emitted by [`view:goto_buffer()`][].
+--   Called right before switching to another buffer.
+--   Emitted by [`view:goto_buffer()`][].
 -- @field BUFFER_DELETED (string)
---   Called after a buffer was deleted.
---   This is emitted by [`buffer:delete()`][].
+--   Called after deleting a buffer.
+--   Emitted by [`buffer:delete()`][].
 -- @field BUFFER_NEW (string)
---   Called when a new buffer is created.
---   This is emitted on startup and by [`new_buffer()`][].
+--   Called after creating a new buffer.
+--   Emitted on startup and by [`new_buffer()`][].
 -- @field CALL_TIP_CLICK (string)
---   Called when the user clicks on a calltip.
+--   Called when clicking on a calltip.
 --   Arguments:
 --
---   * `position`: Set to 1 if the click is in an up arrow, 2 if in a down
---     arrow, and 0 if elsewhere.
+--   * _`position`_: `1` if the up arrow was clicked, 2 if the down arrow was
+--     clicked, and 0 otherwise.
 -- @field CHAR_ADDED (string)
---   Called when an ordinary text character is added to the buffer.
+--   Called after adding an ordinary text character to the buffer.
 --   Arguments:
 --
---   * `ch`: The text character byte.
+--   * _`ch`_: The text character byte.
 -- @field COMMAND_ENTRY_COMMAND (string)
---   Called when a command is entered into the Command Entry.
+--   Called to run the command entered into the Command Entry.
 --   If any handler returns `true`, the Command Entry does not hide
 --   automatically.
 --   Arguments:
 --
---   * `command`: The command text.
+--   * _`command`_: The command text.
 -- @field COMMAND_ENTRY_KEYPRESS (string)
---   Called when a key is pressed in the Command Entry.
+--   Called when pressing a key in the Command Entry.
 --   If any handler returns `true`, the key is not inserted into the entry.
 --   Arguments:
 --
---   * `code`: The key code.
---   * `shift`: The "Shift" modifier key is held down.
---   * `ctrl`: The "Control"/"Command" modifier key is held down.
---   * `alt`: The "Alt"/"Option" modifier key is held down.
---   * `meta`: The "Control" modifier key on Mac OSX is held down.
+--   * _`code`_: The numeric key code.
+--   * _`shift`_: The "Shift" modifier key is held down.
+--   * _`ctrl`_: The "Control"/"Command" modifier key is held down.
+--   * _`alt`_: The "Alt"/"Option" modifier key is held down.
+--   * _`meta`_: The "Control" modifier key on Mac OSX is held down.
 -- @field DOUBLE_CLICK (string)
---   Called when the mouse button is double-clicked.
+--   Called after double-clicking the mouse button.
 --   Arguments:
 --
---   * `position`: The text position of the double click.
---   * `line`: The line of the double click.
---   * `modifiers`: The key modifiers held down. It is a combination of zero or
---     more of `_SCINTILLA.constants.SCMOD_ALT`,
---     `_SCINTILLA.constants.SCMOD_CTRL`,
+--   * _`position`_: The position in the buffer double-clicked.
+--   * _`line`_: The line number double-clicked.
+--   * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are
+--     `_SCINTILLA.constants.SCMOD_ALT`, `_SCINTILLA.constants.SCMOD_CTRL`,
 --     `_SCINTILLA.constants.SCMOD_SHIFT`, and
 --     `_SCINTILLA.constants.SCMOD_META`.
 --     Note: If you set `buffer.rectangular_selection_modifier` to
 --     `_SCINTILLA.constants.SCMOD_CTRL`, the "Control" modifier is reported as
 --     *both* "Control" and "Alt" due to a Scintilla limitation with GTK+.
 -- @field DWELL_END (string)
---   Called after a `DWELL_START` and the mouse is moved or other activity such
---   as key press indicates the dwell is over.
+--   Called after a `DWELL_START` when the mouse moves, a key is pressed, etc.
 --   Arguments:
 --
---   * `position`: The nearest position in the document to the position where
---     the mouse pointer was lingering.
---   * `x`: Where the pointer lingered.
---   * `y`: Where the pointer lingered.
+--   * _`position`_: The position in the buffer closest to *x* and *y*.
+--   * _`x`_: The x-coordinate of the mouse in the view.
+--   * _`y`_: The y-coordinate of the mouse in the view.
 -- @field DWELL_START (string)
---   Called when the user keeps the mouse in one position for the dwell period
---   (see `_SCINTILLA.constants.SCI_SETMOUSEDWELLTIME`).
+--   Called after keeping the mouse stationary for the [dwell period][]
 --   Arguments:
 --
---   * `position`: The nearest position in the document to the position where
---     the mouse pointer was lingering.
---   * `x`: Where the pointer lingered.
---   * `y`: Where the pointer lingered.
+--   * _`position`_: The position in the buffer closest to *x* and *y*.
+--   * _`x`_: The x-coordinate of the mouse in the view.
+--   * _`y`_: The y-coordinate of the mouse in the view.
 -- @field ERROR (string)
 --   Called when an error occurs.
 --   Arguments:
 --
---   * `text`: The error text.
+--   * _`text`_: The error text.
 -- @field FIND (string)
---   Called when finding text via the Find dialog box.
+--   Called to find text via the Find dialog box.
 --   Arguments:
 --
---   * `text`: The text to search for.
---   * `next`: Search forward.
+--   * _`text`_: The text to search for.
+--   * _`next`_: Whether or not to search forward.
 -- @field HOTSPOT_CLICK (string)
---   Called when the user clicks on text that is in a style with the hotspot
---   attribute set.
+--   Called when clicking on text that is in a style with the hotspot attribute
+--   set.
 --   Arguments:
 --
---   * `position`: The text position of the click.
---   * `modifiers`: The key modifiers held down. It is a combination of zero or
---     more of `_SCINTILLA.constants.SCMOD_ALT`,
---     `_SCINTILLA.constants.SCMOD_CTRL`,
+--   * _`position`_: The position in the buffer clicked.
+--   * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are
+--     `_SCINTILLA.constants.SCMOD_ALT`, `_SCINTILLA.constants.SCMOD_CTRL`,
 --     `_SCINTILLA.constants.SCMOD_SHIFT`, and
 --     `_SCINTILLA.constants.SCMOD_META`.
 --     Note: If you set `buffer.rectangular_selection_modifier` to
 --     `_SCINTILLA.constants.SCMOD_CTRL`, the "Control" modifier is reported as
 --     *both* "Control" and "Alt" due to a Scintilla limitation with GTK+.
 -- @field HOTSPOT_DOUBLE_CLICK (string)
---   Called when the user double clicks on text that is in a style with the
---   hotspot attribute set.
+--   Called when double-clicking on text that is in a style with the hotspot
+--   attribute set.
 --   Arguments:
 --
---   * `position`: The text position of the double click.
---   * `modifiers`: The key modifiers held down. It is a combination of zero or
---     more of `_SCINTILLA.constants.SCMOD_ALT`,
---     `_SCINTILLA.constants.SCMOD_CTRL`,
+--   * _`position`_: The position in the buffer double-clicked.
+--   * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are
+--     `_SCINTILLA.constants.SCMOD_ALT`, `_SCINTILLA.constants.SCMOD_CTRL`,
 --     `_SCINTILLA.constants.SCMOD_SHIFT`, and
 --     `_SCINTILLA.constants.SCMOD_META`.
 --     Note: If you set `buffer.rectangular_selection_modifier` to
 --     `_SCINTILLA.constants.SCMOD_CTRL`, the "Control" modifier is reported as
 --     *both* "Control" and "Alt" due to a Scintilla limitation with GTK+.
 -- @field HOTSPOT_RELEASE_CLICK (string)
---   Called when the user releases the mouse on text that is in a style with the
---   hotspot attribute set.
+--   Called after releasing the mouse after clicking on text that was in a style
+--   with the hotspot attribute set.
 --   Arguments:
 --
---   * `position`: The text position of the release.
+--   * _`position`_: The position in the buffer unclicked.
 -- @field INDICATOR_CLICK (string)
---   Called when the user clicks the mouse on text that has an indicator.
+--   Called when clicking the mouse on text that has an indicator.
 --   Arguments:
 --
---   * `position`: The text position of the click.
---   * `modifiers`: The key modifiers held down. It is a combination of zero or
---     more of `_SCINTILLA.constants.SCMOD_ALT`,
---     `_SCINTILLA.constants.SCMOD_CTRL`,
+--   * _`position`_: The position in the buffer clicked.
+--   * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are
+--     `_SCINTILLA.constants.SCMOD_ALT`, `_SCINTILLA.constants.SCMOD_CTRL`,
 --     `_SCINTILLA.constants.SCMOD_SHIFT`, and
 --     `_SCINTILLA.constants.SCMOD_META`.
 --     Note: If you set `buffer.rectangular_selection_modifier` to
 --     `_SCINTILLA.constants.SCMOD_CTRL`, the "Control" modifier is reported as
 --     *both* "Control" and "Alt" due to a Scintilla limitation with GTK+.
 -- @field INDICATOR_RELEASE (string)
---   Called when the user releases the mouse on text that has an indicator.
+--   Called after releasing the mouse after clicking on text that had an
+--   indicator.
 --   Arguments:
 --
---   * `position`: The text position of the release.
+--   * _`position`_: The position in the buffer unclicked.
 -- @field KEYPRESS (string)
---   Called when a key is pressed.
+--   Called when pressing a key.
 --   If any handler returns `true`, the key is not inserted into the buffer.
 --   Arguments:
 --
---   * `code`: The key code.
---   * `shift`: The "Shift" modifier key is held down.
---   * `ctrl`: The "Control"/"Command" modifier key is held down.
---   * `alt`: The "Alt"/"Option" modifier key is held down.
---   * `meta`: The "Control" modifier key on Mac OSX is held down.
+--   * _`code`_: The numeric key code.
+--   * _`shift`_: The "Shift" modifier key is held down.
+--   * _`ctrl`_: The "Control"/"Command" modifier key is held down.
+--   * _`alt`_: The "Alt"/"Option" modifier key is held down.
+--   * _`meta`_: The "Control" modifier key on Mac OSX is held down.
 -- @field MARGIN_CLICK (string)
---   Called when the mouse is clicked inside a margin.
+--   Called when clicking the mouse inside a margin.
 --   Arguments:
 --
---   * `margin`: The margin number that was clicked.
---   * `position`: The position of the start of the line in the buffer that
---     corresponds to the margin click.
---   * `modifiers`: The appropriate combination of
---     `_SCINTILLA.constants.SCI_SHIFT`, `_SCINTILLA.constants.SCI_CTRL`,
---     and `_SCINTILLA.constants.SCI_ALT` to indicate the keys that were held
---     down at the time of the margin click.
+--   * _`margin`_: The margin number clicked.
+--   * _`position`_: The position of the start of the line in the buffer whose
+--     margin line was clicked.
+--   * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are
+--     `_SCINTILLA.constants.SCMOD_ALT`, `_SCINTILLA.constants.SCMOD_CTRL`,
+--     `_SCINTILLA.constants.SCMOD_SHIFT`, and
+--     `_SCINTILLA.constants.SCMOD_META`.
 --     Note: If you set `buffer.rectangular_selection_modifier` to
 --     `_SCINTILLA.constants.SCMOD_CTRL`, the "Control" modifier is reported as
 --     *both* "Control" and "Alt" due to a Scintilla limitation with GTK+.
 -- @field MENU_CLICKED (string)
---   Called when a menu item is selected.
+--   Called after selecting a menu item.
 --   Arguments:
 --
---   * `menu_id`: The numeric ID of the menu item set in [`gui.menu()`][].
+--   * _`menu_id`_: The numeric ID of the menu item set in [`gui.menu()`][].
 -- @field QUIT (string)
 --   Called when quitting Textadept.
 --   When connecting to this event, connect with an index of 1 or the handler
 --   will be ignored.
---   This is emitted by [`quit()`][].
+--   Emitted by [`quit()`][].
 -- @field REPLACE (string)
 --   Called to replace selected (found) text.
 --   Arguments:
 --
---   * `text`: The text to replace selected text with.
+--   * _`text`_: The text to replace the selected text with.
 -- @field REPLACE_ALL (string)
---   Called to replace all occurances of found text.
+--   Called to replace all occurrences of found text.
 --   Arguments:
 --
---   * `find_text`: The text to search for.
---   * `repl_text`: The text to replace found text with.
+--   * _`find_text`_: The text to search for.
+--   * _`repl_text`_: The text to replace found text with.
 -- @field RESET_AFTER (string)
 --   Called after resetting the Lua state.
---   This is emitted by [`reset()`][].
+--   Emitted by [`reset()`][].
 -- @field RESET_BEFORE (string)
 --   Called before resetting the Lua state.
---   This is emitted by [`reset()`][].
+--   Emitted by [`reset()`][].
 -- @field SAVE_POINT_LEFT (string)
---   Called when a save point is left.
+--   Called after leaving a save point.
 -- @field SAVE_POINT_REACHED (string)
---   Called when a save point is entered.
+--   Called after reaching a save point.
 -- @field UPDATE_UI (string)
---   Called when either the text or styling of the buffer has changed or the
---   selection range has changed.
+--   Called when the text, styling, or selection range in the buffer changes.
 -- @field URI_DROPPED (string)
---   Called when the user has dragged a URI such as a file name onto the view.
+--   Called after dragging and dropping a URI such as a file name onto the view.
 --   Arguments:
 --
---   * `text`: The URI text encoded in UTF-8.
+--   * _`text`_: The UTF-8-encoded URI text.
 -- @field USER_LIST_SELECTION (string)
---   Called when the user has selected an item in a user list.
+--   Called after selecting an item in a user list.
 --   Arguments:
 --
---   * `list_type`: This is set to the list_type parameter from the
---     [`buffer:user_list_show()`][] call that initiated the list.
---   * `text`: The text of the selection.
---   * `position`: The position the list was displayed at.
+--   * _`list_type`_: The *list_type* from [`buffer:user_list_show()`][].
+--   * _`text`_: The text of the selection.
+--   * _`position`_: The position in the buffer the list was displayed at.
 -- @field VIEW_NEW (string)
---   Called when a new view is created.
---   This is emitted on startup and by [`view:split()`][].
+--   Called after creating a new view.
+--   Emitted on startup and by [`view:split()`][].
 -- @field VIEW_BEFORE_SWITCH (string)
---   Called right before another view is switched to.
---   This is emitted by [`gui.goto_view()`][].
+--   Called right before switching to another view.
+--   Emitted by [`gui.goto_view()`][].
 -- @field VIEW_AFTER_SWITCH (string)
---   Called right after another view is switched to.
---   This is emitted by [`gui.goto_view()`][].
+--   Called right after switching to another view.
+--   Emitted by [`gui.goto_view()`][].
 --
 -- [`buffer:auto_c_cancel()`]: buffer.html#auto_c_cancel
 -- [`view:goto_buffer()`]: view.html#goto_buffer
 -- [`new_buffer()`]: _G.html#new_buffer
 -- [`buffer:delete()`]: buffer.html#delete
+-- [dwell period]: buffer.html#mouse_dwell_time
 -- [`gui.menu()`]: gui.html#menu
 -- [`quit()`]: _G.html#quit
 -- [`reset()`]: _G.html#reset
@@ -271,18 +263,19 @@ local M = {}
 module('events')]]
 
 ---
--- A table of event names and a table of functions connected to them.
+-- Map of event names with tables of the functions connected to them.
 -- @class table
 -- @name handlers
 M.handlers = {}
 
 ---
--- Adds a handler function to an event.
--- @param event The string event name. It is arbitrary and does not need to be
---   defined previously.
+-- Adds function *f* to the set of event handlers for *event* at position
+-- *index*, returning a handler ID for *f*. *event* is an arbitrary event name
+-- that does not need to have been previously defined.
+-- @param event The string event name.
 -- @param f The Lua function to add.
 -- @param index Optional index to insert the handler into.
--- @return Index of handler.
+-- @return handler ID.
 -- @usage events.connect('my_event', function(msg) gui.print(msg) end)
 -- @see disconnect
 -- @name connect
@@ -295,25 +288,28 @@ function M.connect(event, f, index)
 end
 
 ---
--- Disconnects a handler function from an event.
+-- Removes handler ID *id*, returned by `events.connect()`, from the set of
+-- event handlers for *event*.
 -- @param event The string event name.
--- @param index Index of the handler returned by `events.connect()`.
+-- @param id ID of the handler returned by `events.connect()`.
 -- @see connect
 -- @name disconnect
-function M.disconnect(event, index)
+function M.disconnect(event, id)
   if not M.handlers[event] then return end
-  table.remove(M.handlers[event], index)
+  table.remove(M.handlers[event], id)
 end
 
 local error_emitted = false
 
 ---
--- Calls all handlers for the given event in sequence.
--- If `true` or `false` is explicitly returned by any handler, the event is not
--- propagated any further; iteration ceases. This is useful if you want to stop
--- the propagation of an event like a keypress.
--- @param event The string event name. It is arbitrary and does not need to be
---   defined previously.
+-- Sequentially calls all handler functions for *event* with the given
+-- arguments.
+-- *event* is an arbitrary event name that does not need to have been previously
+-- defined. If any handler explicitly returns `true` or `false`, the event is
+-- not propagated any further, iteration ceases, and `emit()` returns that
+-- value. This is useful for stopping the propagation of an event like a
+-- keypress after it has been handled.
+-- @param event The string event name.
 -- @param ... Arguments passed to the handler.
 -- @return `true` or `false` if any handler explicitly returned such; `nil`
 --   otherwise.
diff --git a/core/file_io.lua b/core/file_io.lua
index 3af44694..6d858d81 100644
--- a/core/file_io.lua
+++ b/core/file_io.lua
@@ -25,33 +25,33 @@
 -- [`string.iconv()`]: string.html#iconv
 -- [`_CHARSET`]: _G.html#_CHARSET
 -- @field _G.events.FILE_OPENED (string)
---   Called when a file is opened in a new buffer.
---   This is emitted by [`open_file()`](#open_file)
+--   Called when opening a file in a new buffer.
+--   Emitted by [`open_file()`](#open_file).
 --   Arguments:
 --
---   * `filename`: The filename encoded in UTF-8.
+--   * _`filename`_: The UTF-8-encoded filename.
 -- @field _G.events.FILE_BEFORE_SAVE (string)
---   Called right before a file is saved to disk.
---   This is emitted by [`buffer:save()`][]
+--   Called right before saving a file to disk.
+--   Emitted by [`buffer:save()`][].
 --   Arguments:
 --
---   * `filename`: The filename encoded in UTF-8.
+--   * _`filename`_: The UTF-8-encoded filename.
 --
 -- [`buffer:save()`]: buffer.html#save
 -- @field _G.events.FILE_AFTER_SAVE (string)
---   Called right after a file is saved to disk.
---   This is emitted by [`buffer:save()`][]
+--   Called right after saving a file to disk.
+--   Emitted by [`buffer:save()`][].
 --   Arguments:
 --
---   * `filename`: The filename encoded in UTF-8.
+--   * _`filename`_: The UTF-8-encoded filename.
 --
 -- [`buffer:save()`]: buffer.html#save
 -- @field _G.events.FILE_SAVED_AS (string)
---   Called when a file is saved under a different filename.
---   This is emitted by [`buffer:save_as()`][]
+--   Called after saving a file under a different filename.
+--   Emitted by [`buffer:save_as()`][].
 --   Arguments:
 --
---   * `filename`: The filename encoded in UTF-8.
+--   * _`filename`_: The UTF-8-encoded filename.
 --
 -- [`buffer:save_as()`]: buffer.html#save_as
 module('io')]]
@@ -64,8 +64,7 @@ events.FILE_AFTER_SAVE = 'file_after_save'
 events.FILE_SAVED_AS = 'file_saved_as'
 
 ---
--- List of recently opened files.
--- The most recent are towards the top.
+-- List of recently opened files, the most recent being towards the top.
 -- @class table
 -- @name recent_files
 io.recent_files = {}
@@ -109,19 +108,41 @@ end
 -- List of encodings to try to decode files as.
 -- You should add to this list if you get a "Conversion failed" error when
 -- trying to open a file whose encoding is not recognized. Valid encodings are
--- [GNU iconv's encodings][].
+-- [GNU iconv's encodings][] and include:
+--
+--   * European: ASCII, ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16}, KOI8-R, KOI8-U,
+--     KOI8-RU, CP{1250,1251,1252,1253,1254,1257}, CP{850,866,1131},
+--     Mac{Roman,CentralEurope,Iceland,Croatian,Romania},
+--     Mac{Cyrillic,Ukraine,Greek,Turkish}, Macintosh.
+--   * Semitic: ISO-8859-{6,8}, CP{1255,1256}, CP862, Mac{Hebrew,Arabic}.
+--   * Japanese: EUC-JP, SHIFT_JIS, CP932, ISO-2022-JP, ISO-2022-JP-2,
+--     ISO-2022-JP-1.
+--   * Chinese: EUC-CN, HZ, GBK, CP936, GB18030, EUC-TW, BIG5, CP950,
+--     BIG5-HKSCS, BIG5-HKSCS:2004, BIG5-HKSCS:2001, BIG5-HKSCS:1999,
+--     ISO-2022-CN, ISO-2022-CN-EXT.
+--   * Korean: EUC-KR, CP949, ISO-2022-KR, JOHAB.
+--   * Armenian: ARMSCII-8.
+--   * Georgian: Georgian-Academy, Georgian-PS.
+--   * Tajik: KOI8-T.
+--   * Kazakh: PT154, RK1048.
+--   * Thai: ISO-8859-11, TIS-620, CP874, MacThai.
+--   * Laotian: MuleLao-1, CP1133.
+--   * Vietnamese: VISCII, TCVN, CP1258.
+--   * Unicode: UTF-8, UCS-2, UCS-2BE, UCS-2LE, UCS-4, UCS-4BE, UCS-4LE, UTF-16,
+--     UTF-16BE, UTF-16LE, UTF-32, UTF-32BE, UTF-32LE, UTF-7, C99, JAVA.
 --
 -- [GNU iconv's encodings]: http://www.gnu.org/software/libiconv/
+-- @usage io.try_encodings[#io.try_encodings + 1] = 'UTF-16'
 -- @class table
 -- @name try_encodings
 io.try_encodings = {'UTF-8', 'ASCII', 'ISO-8859-1', 'MacRoman'}
 
 ---
--- Opens a list of files.
+-- Opens *utf8_filenames*, a "\n" delimited string of UTF-8-encoded filenames,
+-- or user-selected files.
 -- Emits a `FILE_OPENED` event.
--- @param utf8_filenames A "\n" separated list of UTF-8-encoded filenames to
---   open. If `nil`, the user is prompted with a fileselect dialog.
--- @usage io.open_file(utf8_encoded_filename)
+-- @param utf8_filenames Optional list of filenames to open. If `nil`, the user
+--   is prompted with a fileselect dialog.
 -- @see _G.events
 -- @name open_file
 function io.open_file(utf8_filenames)
@@ -276,8 +297,7 @@ local function save_as(buffer, utf8_filename)
 end
 
 ---
--- Saves all dirty buffers to their respective files.
--- @usage io.save_all()
+-- Saves all unsaved buffers to their respective files.
 -- @see buffer.save
 -- @name save_all
 function io.save_all()
@@ -308,10 +328,9 @@ local function close(buffer)
 end
 
 ---
--- Closes all open buffers.
--- If any buffer is dirty, the user is prompted to continue. No buffers are
--- saved automatically. They must be saved manually.
--- @usage io.close_all()
+-- Closes all open buffers, prompting the user to continue with unsaved buffers,
+-- and returning `true` if the user did not cancel.
+-- No buffers are saved automatically. They must be saved manually.
 -- @return `true` if user did not cancel.
 -- @see buffer.close
 -- @name close_all
diff --git a/core/gui.lua b/core/gui.lua
index 635ea7d6..9d86f8f8 100644
--- a/core/gui.lua
+++ b/core/gui.lua
@@ -4,11 +4,13 @@ local gui = gui
 
 --[[ This comment is for LuaDoc.
 ---
--- Utilities for Textadept's user interface.
+-- Utilities for interacting with Textadept's user interface.
 -- @field title (string, Write-only)
 --   The title of the Textadept window.
 -- @field context_menu
---   A [`gui.menu`](#menu) defining the editor's context menu.
+--   The editor's context menu, a [`gui.menu()`](#menu).
+--   This is a low-level field. You probably want to use the higher-level
+--   `_M.textadept.menu.set_contextmenu()`.
 -- @field clipboard_text (string, Read-only)
 --   The text on the clipboard.
 -- @field statusbar_text (string, Write-only)
@@ -65,15 +67,19 @@ function gui._print(buffer_type, ...) pcall(_print, buffer_type, ...) end
 function gui.print(...) gui._print(_L['[Message Buffer]'], ...) end
 
 ---
--- Shortcut function for `gui.dialog('filteredlist', ...)` with "Ok" and
--- "Cancel" buttons.
+-- Convenience function for `gui.dialog('filteredlist', ...)` with "Ok" and
+-- "Cancel" buttons that returns the text or index of the selection depending on
+-- the boolean value of *int_return*.
+-- *title* is the title of the dialog,*columns* is a list of column names, and
+-- *items* is a list of items to show.
 -- @param title The title for the filtered list dialog.
 -- @param columns A column name or list of column names.
 -- @param items An item or list of items.
--- @param int_return If `true`, returns the integer index of the selected item
---   in the filtered list and is not compatible with the `'--select-multiple'`
---   option. The default value is `false`, which returns the string item(s).
--- @param ... Additional parameters to pass to `gui.dialog()`.
+-- @param int_return Optional flag indicating whether to return the integer
+--   index of the selected item in the filtered list or the string selected
+--   item. A `true` value is not compatible with the `'--select-multiple'`
+--   option. The default value is `false`.
+-- @param ... Optional additional parameters to pass to `gui.dialog()`.
 -- @return Either a string or integer on success; `nil` otherwise. In strings,
 --   multiple items are separated by newlines.
 -- @usage gui.filteredlist('Title', 'Foo', {'Bar', 'Baz'})
@@ -99,8 +105,7 @@ function gui.filteredlist(title, columns, items, int_return, ...)
 end
 
 ---
--- Displays a dialog with a list of buffers to switch to and switches to the
--- selected one, if any.
+-- Prompts the user to select a buffer to switch to.
 -- @name switch_buffer
 function gui.switch_buffer()
   local columns, items = {_L['Name'], _L['File']}, {}
@@ -116,20 +121,22 @@ function gui.switch_buffer()
 end
 
 ---
--- Goes to the buffer with the given filename.
--- If the desired buffer is open in a view, goes to that view. Otherwise, opens
--- the buffer in either the `preferred_view` if given, the first view that is
--- not the current one, a split view if `split` is `true`, or the current view.
+-- Goes to the buffer whose filename is *filename* in an existing view,
+-- otherwise splitting the current view if *split* is `true` or going to the
+-- next or *preferred_view* view instead of staying in the current one.
+-- If *sloppy* is `true`, only the last part of *filename* is matched to a
+-- buffer's `filename`.
 -- @param filename The filename of the buffer to go to.
--- @param split If there is only one view, split it and open the buffer in the
---   other view.
--- @param preferred_view When multiple views exist and the desired buffer is not
---   open in any of them, open it in this one.
--- @param sloppy Flag indicating whether or not to not match `filename` to
---   `buffer.filename` exactly. When `true`, matches `filename` to only the last
---   part of `buffer.filename` This is useful for run and compile commands which
---   output relative filenames and paths instead of full ones and it is likely
---   that the file in question is already open. The default value is `false`.
+-- @param split Optional flag indicating whether or not to open the buffer in a
+--   split view if there is only one view. The default value is `false`.
+-- @param preferred_view Optional view to open the desired buffer in if the
+--   buffer is not visible in any other view.
+-- @param sloppy Optional flag indicating whether or not to not match `filename`
+--   to `buffer.filename` exactly. When `true`, matches `filename` to only the
+--   last part of `buffer.filename` This is useful for run and compile commands
+--   which output relative filenames and paths instead of full ones and it is
+--   likely that the file in question is already open. The default value is
+--   `false`.
 -- @name goto_file
 function gui.goto_file(filename, split, preferred_view, sloppy)
   local patt = not sloppy and '^'..filename..'$' or filename..'$'
@@ -152,15 +159,15 @@ end
 local theme_file = not NCURSES and 'theme' or 'theme_term'
 local THEME
 ---
--- Sets the editor theme from the given name.
--- Themes with the given name in the *`_USERHOME`/themes/* directory override
--- themes of the same name in *`_HOME`/themes/*. If the name contains slashes
--- ('\' on Windows, '/' otherwise), it is assumed to be an absolute path to a
--- theme instead of a theme name. An error is thrown if the theme is not found.
--- Any errors in the theme are printed to `io.stderr`. Running Textadept from a
+-- Sets the editor theme name to *name* or the default platform theme.
+-- Themes with *name* in the *`_USERHOME`/themes/* directory override themes of
+-- the same name in *`_HOME`/themes/*. If *name* contains slashes ('\' on
+-- Windows, '/' otherwise), it is assumed to be an absolute path to a theme
+-- instead of a theme name. An error is thrown if the theme is not found. Any
+-- errors in the theme are printed to `io.stderr`. Running Textadept from a
 -- terminal is the easiest way to see errors as they occur.
--- @param name The name or absolute path of a theme. If `nil`, sets the default
---   theme.
+-- @param name Optional name or absolute path of a theme. If `nil`, sets the
+--   default platform theme.
 -- @name set_theme
 function gui.set_theme(name)
   if not name then
@@ -213,9 +220,8 @@ function gui.set_theme(name)
 end
 
 ---
--- Prompts the user to select an editor theme from a filtered list dialog.
--- Themes in the *`_HOME`/themes/* and *`_USERHOME`/themes/* directories are
--- listed.
+-- Prompts the user to select an editor theme from a list of themes found in the
+-- *`_HOME`/themes/* and *`_USERHOME`/themes/* directories.
 -- @name select_theme
 function gui.select_theme()
   local themes, themes_found = {}, {}
@@ -444,10 +450,10 @@ local size
 The functions below are Lua C functions.
 
 ---
--- Displays a [gtdialog][1] of a specified type with the given string arguments.
--- Each argument is like a string in Lua's `arg` table. Tables of strings are
--- allowed as arguments and are expanded in place. This is useful for
--- filtered list dialogs with many items.
+-- Displays a *kind* [gtdialog][1] with the given string arguments to pass to
+-- the dialog and returns a formatted string of the dialog's output.
+-- Table arguments containing strings are allowed and expanded in place. This is
+-- useful for filtered list dialogs with many items.
 -- For more information on gtdialog, see [http://foicica.com/gtdialog][1].
 --
 -- [1]: http://foicica.com/gtdialog
@@ -459,7 +465,7 @@ The functions below are Lua C functions.
 local dialog
 
 ---
--- Gets the current split view structure.
+-- Returns the current split view structure.
 -- This is primarily used in session saving.
 -- @return table of split views. Each split view entry is a table with 4
 --   fields: `1`, `2`, `vertical`, and `size`. `1` and `2` have values of either
@@ -471,11 +477,13 @@ local dialog
 local get_split_table
 
 ---
--- Goes to the specified view.
+-- Goes to view number *n*.
+-- If *relative* is `true`, *n* is an index relative to the index of the current
+-- view in `_G._VIEWS` instead of an absolute index.
 -- Emits `VIEW_BEFORE_SWITCH` and `VIEW_AFTER_SWITCH` events.
 -- @param n A relative or absolute view index in `_G._VIEWS`.
--- @param relative Flag indicating if n is a relative index or not. The default
---   value is `false`.
+-- @param relative Optional flag indicating whether *n* is a relative or
+--   absolute index. The default value is `false` for an absolute index.
 -- @see _G._G._VIEWS
 -- @see events.VIEW_BEFORE_SWITCH
 -- @see events.VIEW_AFTER_SWITCH
@@ -484,10 +492,11 @@ local get_split_table
 local goto_view
 
 ---
--- Creates a menu, returning the userdata.
--- This is a low-level function. You probably want to use the higher-level
--- `_M.textadept.menu.set_menubar()` or `_M.textadept.menu.set_contextmenu()`
--- functions. Emits a `MENU_CLICKED` event when a menu item is selected.
+-- Low-level function for creating a menu from table *menu_table* and returning
+-- the userdata.
+-- You probably want to use the higher-level `_M.textadept.menu.set_menubar()`
+-- or `_M.textadept.menu.set_contextmenu()` functions. Emits a `MENU_CLICKED`
+-- event when a menu item is selected.
 -- @param menu_table A table defining the menu. It is an ordered list of tables
 --   with a string menu item, integer menu ID, and optional GDK keycode and
 --   modifier mask. The latter two are used to display key shortcuts in the
diff --git a/core/iface.lua b/core/iface.lua
index d71f7db7..decc97b0 100644
--- a/core/iface.lua
+++ b/core/iface.lua
@@ -10,22 +10,20 @@ local M = {}
 module('_SCINTILLA')]]
 
 ---
--- Scintilla constants.
--- Each key is a Scintilla constant with its associated numeric value.
+-- Map of Scintilla constant names to their numeric values.
 -- @class table
 -- @name constants
 M.constants = {ANNOTATION_BOXED=2,ANNOTATION_HIDDEN=0,ANNOTATION_STANDARD=1,CARETSTYLE_BLOCK=2,CARETSTYLE_INVISIBLE=0,CARETSTYLE_LINE=1,CARET_EVEN=0x08,CARET_JUMPS=0x10,CARET_SLOP=0x01,CARET_STRICT=0x04,EDGE_BACKGROUND=2,EDGE_LINE=1,EDGE_NONE=0,INDIC0_MASK=0x20,INDIC1_MASK=0x40,INDIC2_MASK=0x80,INDICS_MASK=0xE0,INDIC_BOX=6,INDIC_CONTAINER=8,INDIC_DASH=9,INDIC_DIAGONAL=3,INDIC_DOTBOX=12,INDIC_DOTS=10,INDIC_HIDDEN=5,INDIC_MAX=31,INDIC_PLAIN=0,INDIC_ROUNDBOX=7,INDIC_SQUIGGLE=1,INDIC_SQUIGGLELOW=11,INDIC_SQUIGGLEPIXMAP=13,INDIC_STRAIGHTBOX=8,INDIC_STRIKE=4,INDIC_TT=2,INVALID_POSITION=-1,KEYWORDSET_MAX=8,MARKER_MAX=31,SCEN_CHANGE=768,SCEN_KILLFOCUS=256,SCEN_SETFOCUS=512,SCFIND_MATCHCASE=4,SCFIND_POSIX=0x00400000,SCFIND_REGEXP=0x00200000,SCFIND_WHOLEWORD=2,SCFIND_WORDSTART=0x00100000,SCI_ANNOTATIONGETLINES=2546,SCI_ANNOTATIONGETSTYLE=2543,SCI_ANNOTATIONGETSTYLEOFFSET=2551,SCI_ANNOTATIONGETSTYLES=2545,SCI_ANNOTATIONGETTEXT=2541,SCI_ANNOTATIONGETVISIBLE=2549,SCI_ANNOTATIONSETSTYLE=2542,SCI_ANNOTATIONSETSTYLEOFFSET=2550,SCI_ANNOTATIONSETSTYLES=2544,SCI_ANNOTATIONSETTEXT=2540,SCI_ANNOTATIONSETVISIBLE=2548,SCI_AUTOCGETAUTOHIDE=2119,SCI_AUTOCGETCANCELATSTART=2111,SCI_AUTOCGETCASEINSENSITIVEBEHAVIOUR=2635,SCI_AUTOCGETCHOOSESINGLE=2114,SCI_AUTOCGETCURRENT=2445,SCI_AUTOCGETCURRENTTEXT=2610,SCI_AUTOCGETDROPRESTOFWORD=2271,SCI_AUTOCGETIGNORECASE=2116,SCI_AUTOCGETMAXHEIGHT=2211,SCI_AUTOCGETMAXWIDTH=2209,SCI_AUTOCGETSEPARATOR=2107,SCI_AUTOCGETTYPESEPARATOR=2285,SCI_AUTOCSETAUTOHIDE=2118,SCI_AUTOCSETCANCELATSTART=2110,SCI_AUTOCSETCASEINSENSITIVEBEHAVIOUR=2634,SCI_AUTOCSETCHOOSESINGLE=2113,SCI_AUTOCSETDROPRESTOFWORD=2270,SCI_AUTOCSETFILLUPS=2112,SCI_AUTOCSETIGNORECASE=2115,SCI_AUTOCSETMAXHEIGHT=2210,SCI_AUTOCSETMAXWIDTH=2208,SCI_AUTOCSETSEPARATOR=2106,SCI_AUTOCSETTYPESEPARATOR=2286,SCI_CALLTIPSETBACK=2205,SCI_CALLTIPSETFORE=2206,SCI_CALLTIPSETFOREHLT=2207,SCI_CALLTIPSETPOSITION=2213,SCI_CALLTIPUSESTYLE=2212,SCI_GETADDITIONALCARETFORE=2605,SCI_GETADDITIONALCARETSBLINK=2568,SCI_GETADDITIONALCARETSVISIBLE=2609,SCI_GETADDITIONALSELALPHA=2603,SCI_GETADDITIONALSELECTIONTYPING=2566,SCI_GETALLLINESVISIBLE=2236,SCI_GETANCHOR=2009,SCI_GETBACKSPACEUNINDENTS=2263,SCI_GETBUFFEREDDRAW=2034,SCI_GETCARETFORE=2138,SCI_GETCARETLINEBACK=2097,SCI_GETCARETLINEBACKALPHA=2471,SCI_GETCARETLINEVISIBLE=2095,SCI_GETCARETPERIOD=2075,SCI_GETCARETSTICKY=2457,SCI_GETCARETSTYLE=2513,SCI_GETCARETWIDTH=2189,SCI_GETCHARACTERPOINTER=2520,SCI_GETCHARAT=2007,SCI_GETCODEPAGE=2137,SCI_GETCOLUMN=2129,SCI_GETCONTROLCHARSYMBOL=2389,SCI_GETCURRENTPOS=2008,SCI_GETCURSOR=2387,SCI_GETDIRECTFUNCTION=2184,SCI_GETDIRECTPOINTER=2185,SCI_GETDOCPOINTER=2357,SCI_GETEDGECOLOUR=2364,SCI_GETEDGECOLUMN=2360,SCI_GETEDGEMODE=2362,SCI_GETENDATLASTLINE=2278,SCI_GETENDSTYLED=2028,SCI_GETEOLMODE=2030,SCI_GETEXTRAASCENT=2526,SCI_GETEXTRADESCENT=2528,SCI_GETFIRSTVISIBLELINE=2152,SCI_GETFOCUS=2381,SCI_GETFOLDEXPANDED=2230,SCI_GETFOLDLEVEL=2223,SCI_GETFOLDPARENT=2225,SCI_GETFONTQUALITY=2612,SCI_GETGAPPOSITION=2644,SCI_GETHIGHLIGHTGUIDE=2135,SCI_GETHOTSPOTACTIVEUNDERLINE=2496,SCI_GETHOTSPOTSINGLELINE=2497,SCI_GETHSCROLLBAR=2131,SCI_GETIDENTIFIER=2623,SCI_GETINDENT=2123,SCI_GETINDENTATIONGUIDES=2133,SCI_GETINDICATORCURRENT=2501,SCI_GETINDICATORVALUE=2503,SCI_GETKEYSUNICODE=2522,SCI_GETLAYOUTCACHE=2273,SCI_GETLENGTH=2006,SCI_GETLEXER=4002,SCI_GETLEXERLANGUAGE=4012,SCI_GETLINECOUNT=2154,SCI_GETLINEENDPOSITION=2136,SCI_GETLINEINDENTATION=2127,SCI_GETLINEINDENTPOSITION=2128,SCI_GETLINESTATE=2093,SCI_GETLINEVISIBLE=2228,SCI_GETMAINSELECTION=2575,SCI_GETMARGINCURSORN=2249,SCI_GETMARGINLEFT=2156,SCI_GETMARGINMASKN=2245,SCI_GETMARGINOPTIONS=2557,SCI_GETMARGINRIGHT=2158,SCI_GETMARGINSENSITIVEN=2247,SCI_GETMARGINTYPEN=2241,SCI_GETMARGINWIDTHN=2243,SCI_GETMAXLINESTATE=2094,SCI_GETMODEVENTMASK=2378,SCI_GETMODIFY=2159,SCI_GETMOUSEDOWNCAPTURES=2385,SCI_GETMOUSEDWELLTIME=2265,SCI_GETMULTIPASTE=2615,SCI_GETMULTIPLESELECTION=2564,SCI_GETOVERTYPE=2187,SCI_GETPASTECONVERTENDINGS=2468,SCI_GETPOSITIONCACHE=2515,SCI_GETPRINTCOLOURMODE=2149,SCI_GETPRINTMAGNIFICATION=2147,SCI_GETPRINTWRAPMODE=2407,SCI_GETPROPERTY=4008,SCI_GETPROPERTYEXPANDED=4009,SCI_GETPROPERTYINT=4010,SCI_GETPUNCTUATIONCHARS=2649,SCI_GETREADONLY=2140,SCI_GETRECTANGULARSELECTIONANCHOR=2591,SCI_GETRECTANGULARSELECTIONANCHORVIRTUALSPACE=2595,SCI_GETRECTANGULARSELECTIONCARET=2589,SCI_GETRECTANGULARSELECTIONCARETVIRTUALSPACE=2593,SCI_GETRECTANGULARSELECTIONMODIFIER=2599,SCI_GETSCROLLWIDTH=2275,SCI_GETSCROLLWIDTHTRACKING=2517,SCI_GETSEARCHFLAGS=2199,SCI_GETSELALPHA=2477,SCI_GETSELECTIONEMPTY=2650,SCI_GETSELECTIONEND=2145,SCI_GETSELECTIONMODE=2423,SCI_GETSELECTIONNANCHOR=2579,SCI_GETSELECTIONNANCHORVIRTUALSPACE=2583,SCI_GETSELECTIONNCARET=2577,SCI_GETSELECTIONNCARETVIRTUALSPACE=2581,SCI_GETSELECTIONNEND=2587,SCI_GETSELECTIONNSTART=2585,SCI_GETSELECTIONS=2570,SCI_GETSELECTIONSTART=2143,SCI_GETSELEOLFILLED=2479,SCI_GETSTATUS=2383,SCI_GETSTYLEAT=2010,SCI_GETSTYLEBITS=2091,SCI_GETSTYLEBITSNEEDED=4011,SCI_GETTABINDENTS=2261,SCI_GETTABWIDTH=2121,SCI_GETTAG=2616,SCI_GETTARGETEND=2193,SCI_GETTARGETSTART=2191,SCI_GETTECHNOLOGY=2631,SCI_GETTEXTLENGTH=2183,SCI_GETTWOPHASEDRAW=2283,SCI_GETUNDOCOLLECTION=2019,SCI_GETUSETABS=2125,SCI_GETVIEWEOL=2355,SCI_GETVIEWWS=2020,SCI_GETVIRTUALSPACEOPTIONS=2597,SCI_GETVSCROLLBAR=2281,SCI_GETWHITESPACECHARS=2647,SCI_GETWHITESPACESIZE=2087,SCI_GETWORDCHARS=2646,SCI_GETWRAPINDENTMODE=2473,SCI_GETWRAPMODE=2269,SCI_GETWRAPSTARTINDENT=2465,SCI_GETWRAPVISUALFLAGS=2461,SCI_GETWRAPVISUALFLAGSLOCATION=2463,SCI_GETXOFFSET=2398,SCI_GETZOOM=2374,SCI_INDICGETALPHA=2524,SCI_INDICGETFORE=2083,SCI_INDICGETOUTLINEALPHA=2559,SCI_INDICGETSTYLE=2081,SCI_INDICGETUNDER=2511,SCI_INDICSETALPHA=2523,SCI_INDICSETFORE=2082,SCI_INDICSETOUTLINEALPHA=2558,SCI_INDICSETSTYLE=2080,SCI_INDICSETUNDER=2510,SCI_LEXER_START=4000,SCI_LINESONSCREEN=2370,SCI_MARGINGETSTYLE=2533,SCI_MARGINGETSTYLEOFFSET=2538,SCI_MARGINGETSTYLES=2535,SCI_MARGINGETTEXT=2531,SCI_MARGINSETSTYLE=2532,SCI_MARGINSETSTYLEOFFSET=2537,SCI_MARGINSETSTYLES=2534,SCI_MARGINSETTEXT=2530,SCI_MARKERSETALPHA=2476,SCI_MARKERSETBACK=2042,SCI_MARKERSETBACKSELECTED=2292,SCI_MARKERSETFORE=2041,SCI_OPTIONAL_START=3000,SCI_RGBAIMAGESETHEIGHT=2625,SCI_RGBAIMAGESETSCALE=2651,SCI_RGBAIMAGESETWIDTH=2624,SCI_SELECTIONISRECTANGLE=2372,SCI_SETADDITIONALCARETFORE=2604,SCI_SETADDITIONALCARETSBLINK=2567,SCI_SETADDITIONALCARETSVISIBLE=2608,SCI_SETADDITIONALSELALPHA=2602,SCI_SETADDITIONALSELBACK=2601,SCI_SETADDITIONALSELECTIONTYPING=2565,SCI_SETADDITIONALSELFORE=2600,SCI_SETANCHOR=2026,SCI_SETBACKSPACEUNINDENTS=2262,SCI_SETBUFFEREDDRAW=2035,SCI_SETCARETFORE=2069,SCI_SETCARETLINEBACK=2098,SCI_SETCARETLINEBACKALPHA=2470,SCI_SETCARETLINEVISIBLE=2096,SCI_SETCARETPERIOD=2076,SCI_SETCARETSTICKY=2458,SCI_SETCARETSTYLE=2512,SCI_SETCARETWIDTH=2188,SCI_SETCODEPAGE=2037,SCI_SETCONTROLCHARSYMBOL=2388,SCI_SETCURRENTPOS=2141,SCI_SETCURSOR=2386,SCI_SETDOCPOINTER=2358,SCI_SETEDGECOLOUR=2365,SCI_SETEDGECOLUMN=2361,SCI_SETEDGEMODE=2363,SCI_SETENDATLASTLINE=2277,SCI_SETEOLMODE=2031,SCI_SETEXTRAASCENT=2525,SCI_SETEXTRADESCENT=2527,SCI_SETFIRSTVISIBLELINE=2613,SCI_SETFOCUS=2380,SCI_SETFOLDEXPANDED=2229,SCI_SETFOLDFLAGS=2233,SCI_SETFOLDLEVEL=2222,SCI_SETFONTQUALITY=2611,SCI_SETHIGHLIGHTGUIDE=2134,SCI_SETHOTSPOTACTIVEUNDERLINE=2412,SCI_SETHOTSPOTSINGLELINE=2421,SCI_SETHSCROLLBAR=2130,SCI_SETIDENTIFIER=2622,SCI_SETINDENT=2122,SCI_SETINDENTATIONGUIDES=2132,SCI_SETINDICATORCURRENT=2500,SCI_SETINDICATORVALUE=2502,SCI_SETKEYSUNICODE=2521,SCI_SETKEYWORDS=4005,SCI_SETLAYOUTCACHE=2272,SCI_SETLEXER=4001,SCI_SETLEXERLANGUAGE=4006,SCI_SETLINEINDENTATION=2126,SCI_SETLINESTATE=2092,SCI_SETMAINSELECTION=2574,SCI_SETMARGINCURSORN=2248,SCI_SETMARGINLEFT=2155,SCI_SETMARGINMASKN=2244,SCI_SETMARGINOPTIONS=2539,SCI_SETMARGINRIGHT=2157,SCI_SETMARGINSENSITIVEN=2246,SCI_SETMARGINTYPEN=2240,SCI_SETMARGINWIDTHN=2242,SCI_SETMODEVENTMASK=2359,SCI_SETMOUSEDOWNCAPTURES=2384,SCI_SETMOUSEDWELLTIME=2264,SCI_SETMULTIPASTE=2614,SCI_SETMULTIPLESELECTION=2563,SCI_SETOVERTYPE=2186,SCI_SETPASTECONVERTENDINGS=2467,SCI_SETPOSITIONCACHE=2514,SCI_SETPRINTCOLOURMODE=2148,SCI_SETPRINTMAGNIFICATION=2146,SCI_SETPRINTWRAPMODE=2406,SCI_SETPROPERTY=4004,SCI_SETPUNCTUATIONCHARS=2648,SCI_SETREADONLY=2171,SCI_SETRECTANGULARSELECTIONANCHOR=2590,SCI_SETRECTANGULARSELECTIONANCHORVIRTUALSPACE=2594,SCI_SETRECTANGULARSELECTIONCARET=2588,SCI_SETRECTANGULARSELECTIONCARETVIRTUALSPACE=2592,SCI_SETRECTANGULARSELECTIONMODIFIER=2598,SCI_SETSCROLLWIDTH=2274,SCI_SETSCROLLWIDTHTRACKING=2516,SCI_SETSEARCHFLAGS=2198,SCI_SETSELALPHA=2478,SCI_SETSELECTIONEND=2144,SCI_SETSELECTIONMODE=2422,SCI_SETSELECTIONNANCHOR=2578,SCI_SETSELECTIONNANCHORVIRTUALSPACE=2582,SCI_SETSELECTIONNCARET=2576,SCI_SETSELECTIONNCARETVIRTUALSPACE=2580,SCI_SETSELECTIONNEND=2586,SCI_SETSELECTIONNSTART=2584,SCI_SETSELECTIONSTART=2142,SCI_SETSELEOLFILLED=2480,SCI_SETSTATUS=2382,SCI_SETSTYLEBITS=2090,SCI_SETTABINDENTS=2260,SCI_SETTABWIDTH=2036,SCI_SETTARGETEND=2192,SCI_SETTARGETSTART=2190,SCI_SETTECHNOLOGY=2630,SCI_SETTWOPHASEDRAW=2284,SCI_SETUNDOCOLLECTION=2012,SCI_SETUSETABS=2124,SCI_SETVIEWEOL=2356,SCI_SETVIEWWS=2021,SCI_SETVIRTUALSPACEOPTIONS=2596,SCI_SETVSCROLLBAR=2280,SCI_SETWHITESPACECHARS=2443,SCI_SETWHITESPACESIZE=2086,SCI_SETWORDCHARS=2077,SCI_SETWRAPINDENTMODE=2472,SCI_SETWRAPMODE=2268,SCI_SETWRAPSTARTINDENT=2464,SCI_SETWRAPVISUALFLAGS=2460,SCI_SETWRAPVISUALFLAGSLOCATION=2462,SCI_SETXOFFSET=2397,SCI_SETZOOM=2373,SCI_START=2000,SCI_STYLEGETBACK=2482,SCI_STYLEGETBOLD=2483,SCI_STYLEGETCASE=2489,SCI_STYLEGETCHANGEABLE=2492,SCI_STYLEGETCHARACTERSET=2490,SCI_STYLEGETEOLFILLED=2487,SCI_STYLEGETFONT=2486,SCI_STYLEGETFORE=2481,SCI_STYLEGETHOTSPOT=2493,SCI_STYLEGETITALIC=2484,SCI_STYLEGETSIZE=2485,SCI_STYLEGETSIZEFRACTIONAL=2062,SCI_STYLEGETUNDERLINE=2488,SCI_STYLEGETVISIBLE=2491,SCI_STYLEGETWEIGHT=2064,SCI_STYLESETBACK=2052,SCI_STYLESETBOLD=2053,SCI_STYLESETCASE=2060,SCI_STYLESETCHANGEABLE=2099,SCI_STYLESETCHARACTERSET=2066,SCI_STYLESETEOLFILLED=2057,SCI_STYLESETFONT=2056,SCI_STYLESETFORE=2051,SCI_STYLESETHOTSPOT=2409,SCI_STYLESETITALIC=2054,SCI_STYLESETSIZE=2055,SCI_STYLESETSIZEFRACTIONAL=2061,SCI_STYLESETUNDERLINE=2059,SCI_STYLESETVISIBLE=2074,SCI_STYLESETWEIGHT=2063,SCK_ADD=310,SCK_BACK=8,SCK_DELETE=308,SCK_DIVIDE=312,SCK_DOWN=300,SCK_END=305,SCK_ESCAPE=7,SCK_HOME=304,SCK_INSERT=309,SCK_LEFT=302,SCK_MENU=315,SCK_NEXT=307,SCK_PRIOR=306,SCK_RETURN=13,SCK_RIGHT=303,SCK_RWIN=314,SCK_SUBTRACT=311,SCK_TAB=9,SCK_UP=301,SCK_WIN=313,SCMOD_ALT=4,SCMOD_CTRL=2,SCMOD_META=16,SCMOD_NORM=0,SCMOD_SHIFT=1,SCMOD_SUPER=8,SCVS_NONE=0,SCVS_RECTANGULARSELECTION=1,SCVS_USERACCESSIBLE=2,SCWS_INVISIBLE=0,SCWS_VISIBLEAFTERINDENT=2,SCWS_VISIBLEALWAYS=1,SC_ALPHA_NOALPHA=256,SC_ALPHA_OPAQUE=255,SC_ALPHA_TRANSPARENT=0,SC_CACHE_CARET=1,SC_CACHE_DOCUMENT=3,SC_CACHE_NONE=0,SC_CACHE_PAGE=2,SC_CARETSTICKY_OFF=0,SC_CARETSTICKY_ON=1,SC_CARETSTICKY_WHITESPACE=2,SC_CASEINSENSITIVEBEHAVIOUR_IGNORECASE=1,SC_CASEINSENSITIVEBEHAVIOUR_RESPECTCASE=0,SC_CASE_LOWER=2,SC_CASE_MIXED=0,SC_CASE_UPPER=1,SC_CHARSET_8859_15=1000,SC_CHARSET_ANSI=0,SC_CHARSET_ARABIC=178,SC_CHARSET_BALTIC=186,SC_CHARSET_CHINESEBIG5=136,SC_CHARSET_CYRILLIC=1251,SC_CHARSET_DEFAULT=1,SC_CHARSET_EASTEUROPE=238,SC_CHARSET_GB2312=134,SC_CHARSET_GREEK=161,SC_CHARSET_HANGUL=129,SC_CHARSET_HEBREW=177,SC_CHARSET_JOHAB=130,SC_CHARSET_MAC=77,SC_CHARSET_OEM=255,SC_CHARSET_RUSSIAN=204,SC_CHARSET_SHIFTJIS=128,SC_CHARSET_SYMBOL=2,SC_CHARSET_THAI=222,SC_CHARSET_TURKISH=162,SC_CHARSET_VIETNAMESE=163,SC_CP_UTF8=65001,SC_CURSORARROW=2,SC_CURSORNORMAL=-1,SC_CURSORREVERSEARROW=7,SC_CURSORWAIT=4,SC_EFF_QUALITY_ANTIALIASED=2,SC_EFF_QUALITY_DEFAULT=0,SC_EFF_QUALITY_LCD_OPTIMIZED=3,SC_EFF_QUALITY_MASK=0xF,SC_EFF_QUALITY_NON_ANTIALIASED=1,SC_EOL_CR=1,SC_EOL_CRLF=0,SC_EOL_LF=2,SC_FOLDFLAG_LEVELNUMBERS=0x0040,SC_FOLDFLAG_LINEAFTER_CONTRACTED=0x0010,SC_FOLDFLAG_LINEAFTER_EXPANDED=0x0008,SC_FOLDFLAG_LINEBEFORE_CONTRACTED=0x0004,SC_FOLDFLAG_LINEBEFORE_EXPANDED=0x0002,SC_FOLDLEVELBASE=0x400,SC_FOLDLEVELHEADERFLAG=0x2000,SC_FOLDLEVELNUMBERMASK=0x0FFF,SC_FOLDLEVELWHITEFLAG=0x1000,SC_FONT_SIZE_MULTIPLIER=100,SC_IV_LOOKBOTH=3,SC_IV_LOOKFORWARD=2,SC_IV_NONE=0,SC_IV_REAL=1,SC_LASTSTEPINUNDOREDO=0x100,SC_MARGINOPTION_NONE=0,SC_MARGINOPTION_SUBLINESELECT=1,SC_MARGIN_BACK=2,SC_MARGIN_FORE=3,SC_MARGIN_NUMBER=1,SC_MARGIN_RTEXT=5,SC_MARGIN_SYMBOL=0,SC_MARGIN_TEXT=4,SC_MARKNUM_FOLDER=30,SC_MARKNUM_FOLDEREND=25,SC_MARKNUM_FOLDERMIDTAIL=27,SC_MARKNUM_FOLDEROPEN=31,SC_MARKNUM_FOLDEROPENMID=26,SC_MARKNUM_FOLDERSUB=29,SC_MARKNUM_FOLDERTAIL=28,SC_MARK_ARROW=2,SC_MARK_ARROWDOWN=6,SC_MARK_ARROWS=24,SC_MARK_AVAILABLE=28,SC_MARK_BACKGROUND=22,SC_MARK_BOXMINUS=14,SC_MARK_BOXMINUSCONNECTED=15,SC_MARK_BOXPLUS=12,SC_MARK_BOXPLUSCONNECTED=13,SC_MARK_CHARACTER=10000,SC_MARK_CIRCLE=0,SC_MARK_CIRCLEMINUS=20,SC_MARK_CIRCLEMINUSCONNECTED=21,SC_MARK_CIRCLEPLUS=18,SC_MARK_CIRCLEPLUSCONNECTED=19,SC_MARK_DOTDOTDOT=23,SC_MARK_EMPTY=5,SC_MARK_FULLRECT=26,SC_MARK_LCORNER=10,SC_MARK_LCORNERCURVE=16,SC_MARK_LEFTRECT=27,SC_MARK_MINUS=7,SC_MARK_PIXMAP=25,SC_MARK_PLUS=8,SC_MARK_RGBAIMAGE=30,SC_MARK_ROUNDRECT=1,SC_MARK_SHORTARROW=4,SC_MARK_SMALLRECT=3,SC_MARK_TCORNER=11,SC_MARK_TCORNERCURVE=17,SC_MARK_UNDERLINE=29,SC_MARK_VLINE=9,SC_MASK_FOLDERS=-33554432,SC_MODEVENTMASKALL=0xFFFFF,SC_MOD_BEFOREDELETE=0x800,SC_MOD_BEFOREINSERT=0x400,SC_MOD_CHANGEANNOTATION=0x20000,SC_MOD_CHANGEFOLD=0x8,SC_MOD_CHANGEINDICATOR=0x4000,SC_MOD_CHANGELINESTATE=0x8000,SC_MOD_CHANGEMARGIN=0x10000,SC_MOD_CHANGEMARKER=0x200,SC_MOD_CHANGESTYLE=0x4,SC_MOD_CONTAINER=0x40000,SC_MOD_DELETETEXT=0x2,SC_MOD_INSERTTEXT=0x1,SC_MOD_LEXERSTATE=0x80000,SC_MULTILINEUNDOREDO=0x1000,SC_MULTIPASTE_EACH=1,SC_MULTIPASTE_ONCE=0,SC_MULTISTEPUNDOREDO=0x80,SC_PERFORMED_REDO=0x40,SC_PERFORMED_UNDO=0x20,SC_PERFORMED_USER=0x10,SC_PRINT_BLACKONWHITE=2,SC_PRINT_COLOURONWHITE=3,SC_PRINT_COLOURONWHITEDEFAULTBG=4,SC_PRINT_INVERTLIGHT=1,SC_PRINT_NORMAL=0,SC_SEL_LINES=2,SC_SEL_RECTANGLE=1,SC_SEL_STREAM=0,SC_SEL_THIN=3,SC_STARTACTION=0x2000,SC_STATUS_BADALLOC=2,SC_STATUS_FAILURE=1,SC_STATUS_OK=0,SC_TECHNOLOGY_DEFAULT=0,SC_TECHNOLOGY_DIRECTWRITE=1,SC_TIME_FOREVER=10000000,SC_TYPE_BOOLEAN=0,SC_TYPE_INTEGER=1,SC_TYPE_STRING=2,SC_UPDATE_CONTENT=0x1,SC_UPDATE_H_SCROLL=0x8,SC_UPDATE_SELECTION=0x2,SC_UPDATE_V_SCROLL=0x4,SC_WEIGHT_BOLD=700,SC_WEIGHT_NORMAL=400,SC_WEIGHT_SEMIBOLD=600,SC_WRAPINDENT_FIXED=0,SC_WRAPINDENT_INDENT=2,SC_WRAPINDENT_SAME=1,SC_WRAPVISUALFLAGLOC_DEFAULT=0x0000,SC_WRAPVISUALFLAGLOC_END_BY_TEXT=0x0001,SC_WRAPVISUALFLAGLOC_START_BY_TEXT=0x0002,SC_WRAPVISUALFLAG_END=0x0001,SC_WRAPVISUALFLAG_MARGIN=0x0004,SC_WRAPVISUALFLAG_NONE=0x0000,SC_WRAPVISUALFLAG_START=0x0002,SC_WRAP_CHAR=2,SC_WRAP_NONE=0,SC_WRAP_WORD=1,STYLE_BRACEBAD=35,STYLE_BRACELIGHT=34,STYLE_CALLTIP=38,STYLE_CONTROLCHAR=36,STYLE_DEFAULT=32,STYLE_INDENTGUIDE=37,STYLE_LASTPREDEFINED=39,STYLE_LINENUMBER=33,STYLE_MAX=255,UNDO_MAY_COALESCE=1,VISIBLE_SLOP=0x01,VISIBLE_STRICT=0x04,SCN_DOUBLECLICK=2006,SCN_AUTOCCHARDELETED=2027,SCN_SAVEPOINTLEFT=2003,SCN_PAINTED=2013,SCN_HOTSPOTRELEASECLICK=2028,SCN_UPDATEUI=2007,SCN_STYLENEEDED=2000,SCN_AUTOCCANCELLED=2026,SCN_MACRORECORD=2009,SCN_INDICATORRELEASE=2024,SCN_MODIFIED=2008,SCN_SAVEPOINTREACHED=2002,SCN_HOTSPOTDOUBLECLICK=2020,SCN_NEEDSHOWN=2011,SCN_CALLTIPCLICK=2021,SCN_AUTOCSELECTION=2022,SCN_DWELLEND=2017,SCN_ZOOM=2018,SCN_CHARADDED=2001,SCN_HOTSPOTCLICK=2019,SCN_KEY=2005,SCN_DWELLSTART=2016,SCN_MARGINCLICK=2010,SCN_USERLISTSELECTION=2014,SCN_URIDROPPED=2015,SCN_INDICATORCLICK=2023,SCN_MODIFYATTEMPTRO=2004,SCLEX_CONTAINER=0,SCLEX_AUTOMATIC=1000,SCLEX_LPEG=999,SCLEX_NULL=1}
 
 ---
--- Scintilla functions.
--- Each key is a Scintilla function name with a table value containing its ID,
--- return type, wParam type, and lParam type. Types are as follows:
+-- Map of Scintilla function names to tables containing their IDs, return types,
+-- wParam types, and lParam types. Types are as follows:
 --
 --   + `0`: Void.
 --   + `1`: Integer.
 --   + `2`: Length of the given lParam string.
 --   + `3`: Integer position.
---   + `4`: Colour in "0xBBGGRR" format.
+--   + `4`: Color, in "0xBBGGRR" format.
 --   + `5`: Boolean `true` or `false`.
 --   + `6`: Bitmask of Scintilla key modifiers and a key value.
 --   + `7`: String parameter.
@@ -35,11 +33,10 @@ M.constants = {ANNOTATION_BOXED=2,ANNOTATION_HIDDEN=0,ANNOTATION_STANDARD=1,CARE
 M.functions = {add_ref_document={2376,0,0,1},add_selection={2573,1,1,1},add_styled_text={2002,0,2,9},add_text={2001,0,2,7},add_undo_action={2560,0,1,1},allocate={2446,0,1,0},annotation_clear_all={2547,0,0,0},append_text={2282,0,2,7},assign_cmd_key={2070,0,6,1},auto_c_active={2102,5,0,0},auto_c_cancel={2101,0,0,0},auto_c_complete={2104,0,0,0},auto_c_pos_start={2103,3,0,0},auto_c_select={2108,0,0,7},auto_c_show={2100,0,1,7},auto_c_stops={2105,0,0,7},back_tab={2328,0,0,0},begin_undo_action={2078,0,0,0},brace_bad_light={2352,0,3,0},brace_bad_light_indicator={2499,0,5,1},brace_highlight={2351,0,3,3},brace_highlight_indicator={2498,0,5,1},brace_match={2353,3,3,0},call_tip_active={2202,5,0,0},call_tip_cancel={2201,0,0,0},call_tip_pos_start={2203,3,0,0},call_tip_set_hlt={2204,0,1,1},call_tip_show={2200,0,3,7},can_paste={2173,5,0,0},can_redo={2016,5,0,0},can_undo={2174,5,0,0},cancel={2325,0,0,0},change_lexer_state={2617,1,3,3},char_left={2304,0,0,0},char_left_extend={2305,0,0,0},char_left_rect_extend={2428,0,0,0},char_position_from_point={2561,3,1,1},char_position_from_point_close={2562,3,1,1},char_right={2306,0,0,0},char_right_extend={2307,0,0,0},char_right_rect_extend={2429,0,0,0},choose_caret_x={2399,0,0,0},clear={2180,0,0,0},clear_all={2004,0,0,0},clear_all_cmd_keys={2072,0,0,0},clear_cmd_key={2071,0,6,0},clear_document_style={2005,0,0,0},clear_registered_images={2408,0,0,0},clear_selections={2571,0,0,0},colourise={4003,0,3,3},contracted_fold_next={2618,1,1,0},convert_eo_ls={2029,0,1,0},copy={2178,0,0,0},copy_allow_line={2519,0,0,0},copy_range={2419,0,3,3},copy_text={2420,0,2,7},count_characters={2633,1,1,1},create_document={2375,1,0,0},create_loader={2632,1,1,0},cut={2177,0,0,0},del_line_left={2395,0,0,0},del_line_right={2396,0,0,0},del_word_left={2335,0,0,0},del_word_right={2336,0,0,0},del_word_right_end={2518,0,0,0},delete_back={2326,0,0,0},delete_back_not_line={2344,0,0,0},delete_range={2645,0,3,1},describe_key_word_sets={4017,1,0,8},describe_property={4016,1,7,8},doc_line_from_visible={2221,1,1,0},document_end={2318,0,0,0},document_end_extend={2319,0,0,0},document_start={2316,0,0,0},document_start_extend={2317,0,0,0},edit_toggle_overtype={2324,0,0,0},empty_undo_buffer={2175,0,0,0},encoded_from_utf8={2449,1,7,8},end_undo_action={2079,0,0,0},ensure_visible={2232,0,1,0},ensure_visible_enforce_policy={2234,0,1,0},find_column={2456,1,1,1},find_indicator_flash={2641,0,3,3},find_indicator_hide={2642,0,0,0},find_indicator_show={2640,0,3,3},find_text={2150,3,1,11},form_feed={2330,0,0,0},format_range={2151,3,5,12},get_cur_line={2027,1,2,8},get_hotspot_active_back={2495,4,0,0},get_hotspot_active_fore={2494,4,0,0},get_last_child={2224,1,1,1},get_line={2153,1,1,8},get_line_sel_end_position={2425,3,1,0},get_line_sel_start_position={2424,3,1,0},get_range_pointer={2643,1,1,1},get_sel_text={2161,1,0,8},get_styled_text={2015,1,0,10},get_text={2182,1,2,8},get_text_range={2162,1,0,10},goto_line={2024,0,1,0},goto_pos={2025,0,3,0},grab_focus={2400,0,0,0},hide_lines={2227,0,1,1},hide_selection={2163,0,5,0},home={2312,0,0,0},home_display={2345,0,0,0},home_display_extend={2346,0,0,0},home_extend={2313,0,0,0},home_rect_extend={2430,0,0,0},home_wrap={2349,0,0,0},home_wrap_extend={2450,0,0,0},indicator_all_on_for={2506,1,1,0},indicator_clear_range={2505,0,1,1},indicator_end={2509,1,1,1},indicator_fill_range={2504,0,1,1},indicator_start={2508,1,1,1},indicator_value_at={2507,1,1,1},insert_text={2003,0,3,7},line_copy={2455,0,0,0},line_cut={2337,0,0,0},line_delete={2338,0,0,0},line_down={2300,0,0,0},line_down_extend={2301,0,0,0},line_down_rect_extend={2426,0,0,0},line_duplicate={2404,0,0,0},line_end={2314,0,0,0},line_end_display={2347,0,0,0},line_end_display_extend={2348,0,0,0},line_end_extend={2315,0,0,0},line_end_rect_extend={2432,0,0,0},line_end_wrap={2451,0,0,0},line_end_wrap_extend={2452,0,0,0},line_from_position={2166,1,3,0},line_length={2350,1,1,0},line_scroll={2168,0,1,1},line_scroll_down={2342,0,0,0},line_scroll_up={2343,0,0,0},line_transpose={2339,0,0,0},line_up={2302,0,0,0},line_up_extend={2303,0,0,0},line_up_rect_extend={2427,0,0,0},lines_join={2288,0,0,0},lines_split={2289,0,1,0},load_lexer_library={4007,0,0,7},lower_case={2340,0,0,0},margin_text_clear_all={2536,0,0,0},marker_add={2043,1,1,1},marker_add_set={2466,0,1,1},marker_define={2040,0,1,1},marker_define_pixmap={2049,0,1,7},marker_define_rgba_image={2626,0,1,7},marker_delete={2044,0,1,1},marker_delete_all={2045,0,1,0},marker_delete_handle={2018,0,1,0},marker_enable_highlight={2293,0,5,0},marker_get={2046,1,1,0},marker_line_from_handle={2017,1,1,0},marker_next={2047,1,1,1},marker_previous={2048,1,1,1},marker_symbol_defined={2529,1,1,0},move_caret_inside_view={2401,0,0,0},move_selected_lines_down={2621,0,0,0},move_selected_lines_up={2620,0,0,0},new_line={2329,0,0,0},null={2172,0,0,0},page_down={2322,0,0,0},page_down_extend={2323,0,0,0},page_down_rect_extend={2434,0,0,0},page_up={2320,0,0,0},page_up_extend={2321,0,0,0},page_up_rect_extend={2433,0,0,0},para_down={2413,0,0,0},para_down_extend={2414,0,0,0},para_up={2415,0,0,0},para_up_extend={2416,0,0,0},paste={2179,0,0,0},point_x_from_position={2164,1,0,3},point_y_from_position={2165,1,0,3},position_after={2418,3,3,0},position_before={2417,3,3,0},position_from_line={2167,3,1,0},position_from_point={2022,3,1,1},position_from_point_close={2023,3,1,1},private_lexer_call={4013,1,1,1},property_names={4014,1,0,8},property_type={4015,1,7,0},redo={2011,0,0,0},register_image={2405,0,1,7},register_rgba_image={2627,0,1,7},release_document={2377,0,0,1},replace_sel={2170,0,0,7},replace_target={2194,1,2,7},replace_target_re={2195,1,2,7},rotate_selection={2606,0,0,0},scroll_caret={2169,0,0,0},scroll_to_end={2629,0,0,0},scroll_to_start={2628,0,0,0},search_anchor={2366,0,0,0},search_in_target={2197,1,2,7},search_next={2367,1,1,7},search_prev={2368,1,1,7},select_all={2013,0,0,0},selection_duplicate={2469,0,0,0},set_chars_default={2444,0,0,0},set_empty_selection={2556,0,3,0},set_fold_margin_colour={2290,0,5,4},set_fold_margin_hi_colour={2291,0,5,4},set_hotspot_active_back={2411,0,5,4},set_hotspot_active_fore={2410,0,5,4},set_length_for_encode={2448,0,1,0},set_save_point={2014,0,0,0},set_sel={2160,0,3,3},set_sel_back={2068,0,5,4},set_sel_fore={2067,0,5,4},set_selection={2572,1,1,1},set_styling={2033,0,2,1},set_styling_ex={2073,0,2,7},set_text={2181,0,0,7},set_visible_policy={2394,0,1,1},set_whitespace_back={2085,0,5,4},set_whitespace_fore={2084,0,5,4},set_x_caret_policy={2402,0,1,1},set_y_caret_policy={2403,0,1,1},show_lines={2226,0,1,1},start_record={3001,0,0,0},start_styling={2032,0,3,1},stop_record={3002,0,0,0},stuttered_page_down={2437,0,0,0},stuttered_page_down_extend={2438,0,0,0},stuttered_page_up={2435,0,0,0},stuttered_page_up_extend={2436,0,0,0},style_clear_all={2050,0,0,0},style_reset_default={2058,0,0,0},swap_main_anchor_caret={2607,0,0,0},tab={2327,0,0,0},target_as_utf8={2447,1,0,8},target_from_selection={2287,0,0,0},text_height={2279,1,1,0},text_width={2276,1,1,7},toggle_caret_sticky={2459,0,0,0},toggle_fold={2231,0,1,0},undo={2176,0,0,0},upper_case={2341,0,0,0},use_pop_up={2371,0,5,0},user_list_show={2117,0,1,7},vc_home={2331,0,0,0},vc_home_display={2652,0,0,0},vc_home_display_extend={2653,0,0,0},vc_home_extend={2332,0,0,0},vc_home_rect_extend={2431,0,0,0},vc_home_wrap={2453,0,0,0},vc_home_wrap_extend={2454,0,0,0},vertical_centre_caret={2619,0,0,0},visible_from_doc_line={2220,1,1,0},word_end_position={2267,1,3,5},word_left={2308,0,0,0},word_left_end={2439,0,0,0},word_left_end_extend={2440,0,0,0},word_left_extend={2309,0,0,0},word_part_left={2390,0,0,0},word_part_left_extend={2391,0,0,0},word_part_right={2392,0,0,0},word_part_right_extend={2393,0,0,0},word_right={2310,0,0,0},word_right_end={2441,0,0,0},word_right_end_extend={2442,0,0,0},word_right_extend={2311,0,0,0},word_start_position={2266,1,3,5},wrap_count={2235,1,1,0},zoom_in={2333,0,0,0},zoom_out={2334,0,0,0}}
 
 ---
--- Scintilla properties.
--- Each key is a Scintilla property name with a table value containing the ID of
--- its "get" function, the ID of its "set" function, its return type, and its
--- wParam type. The wParam type will be non-zero if the property is an indexable
--- property. Types are the same as in the `functions` table.
+-- Map of Scintilla property names to table values containing their "get"
+-- function IDs, "set" function IDs, return types, and wParam types.
+-- The wParam type will be non-zero if the property is indexable.
+-- Types are the same as in the `functions` table.
 -- @see functions
 -- @class table
 -- @name properties
@@ -48,7 +45,7 @@ M.properties = {additional_caret_fore={2605,2604,4,0},additional_carets_blink={2
 local marker_number, indic_number, list_type = -1, 7, 0
 
 ---
--- Returns a unique marker number.
+-- Returns a unique marker number for use with `buffer.marker_define()`.
 -- Use this function for custom markers in order to prevent clashes with
 -- identifiers of other custom markers.
 -- @usage local marknum = _SCINTILLA.next_marker_number()
@@ -60,7 +57,7 @@ function M.next_marker_number()
 end
 
 ---
--- Returns a unique indicator number.
+-- Returns a unique indicator number for use with custom indicators.
 -- Use this function for custom indicators in order to prevent clashes with
 -- identifiers of other custom indicators.
 -- @usage local indic_num = _SCINTILLA.next_indic_number()
@@ -72,7 +69,7 @@ function M.next_indic_number()
 end
 
 ---
--- Returns a unique user list type.
+-- Returns a unique user list type for use with `buffer.user_list_show()`.
 -- Use this function for custom user lists in order to prevent clashes with
 -- list identifiers of other custom user lists.
 -- @usage local list_type = _SCINTILLA.next_user_list_type()
diff --git a/core/init.lua b/core/init.lua
index e0efd459..8ac2dade 100644
--- a/core/init.lua
+++ b/core/init.lua
@@ -23,16 +23,16 @@ _M = {} -- modules table
 ---
 -- Extends Lua's _G table to provide extra functions and fields for Textadept.
 -- @field _HOME (string)
---   Path to the directory containing Textadept.
+--   The path to the directory containing Textadept.
 -- @field _LEXERPATH (string)
---   Paths to lexers, formatted like [`package.path`][].
+--   The paths to lexers, formatted like Lua's [`package.path`][].
 --
 --   [`package.path`]: http://lua.org/manual/5.2/manual.html#pdf-package.path
 -- @field _RELEASE (string)
---   The Textadept release version.
+--   The Textadept release version string.
 -- @field _USERHOME (string)
---   Path to the user's *~/.textadept/*, where all preferences and user-data is
---   stored.
+--   The path to the user's *~/.textadept/* directory, where all preferences and
+--   user-data is stored.
 --   On Windows machines *~/* is the value of the "USERHOME" environment
 --   variable, typically *C:\Users\username\\* or
 --   *C:\Documents and Settings\username\\*. On Linux, BSD, and Mac OSX
@@ -53,16 +53,12 @@ _M = {} -- modules table
 --   ncurses feature incompatibilities are listed in the [Appendix][].
 --
 --   [Appendix]: ../14_Appendix.html#Ncurses.Compatibility
--- @field buffer The current [buffer][] in the current [view](#view).
---
--- [buffer]: buffer.html
--- @field view The currently focused [view](view.html).
 module('_G')]]
 
 --[[ The tables below were defined in C.
 
 ---
--- Command line parameters passed to Textadept.
+-- Table of command line parameters passed to Textadept.
 -- @class table
 -- @see _G.args
 -- @name arg
@@ -73,8 +69,8 @@ local arg
 -- Numeric keys have buffer values and buffer keys have their associated numeric
 -- keys.
 -- @class table
--- @usage _BUFFERS[1] contains the first buffer.
--- @usage _BUFFERS[buffer] returns the index of the current buffer in _BUFFERS.
+-- @usage _BUFFERS[n]      --> buffer at index n
+-- @usage _BUFFERS[buffer] --> index of buffer in _BUFFERS
 -- @see _G.buffer
 -- @name _BUFFERS
 local _BUFFERS
@@ -84,16 +80,28 @@ local _BUFFERS
 -- Numeric keys have view values and view keys have their associated numeric
 -- keys.
 -- @class table
--- @usage _VIEWS[1] contains the first view.
--- @usage _VIEWS[view] returns the index of the current view in _VIEWS.
+-- @usage _VIEWS[n]    --> view at index n
+-- @usage _VIEWS[view] --> index of view in _VIEWS
 -- @see _G.view
 -- @name _VIEWS
 local _VIEWS
 
+---
+-- The current [buffer](buffer.html) in the current [view](#view).
+-- @class table
+-- @name buffer
+local buffer
+
+---
+-- The currently focused [view](view.html).
+-- @class table
+-- @name view
+local view
+
 -- The functions below are Lua C functions.
 
 ---
--- Creates a new buffer.
+-- Creates and returns a new buffer.
 -- Emits a `BUFFER_NEW` event.
 -- @return the new buffer.
 -- @class function
@@ -102,16 +110,15 @@ local _VIEWS
 local new_buffer
 
 ---
--- Quits Textadept.
--- Emits a `QUIT` event. If any handler returns `false`, Textadept does not
--- quit.
+-- Emits a `QUIT` event, and unless any handler returns `false`, quits
+-- Textadept.
 -- @see events.QUIT
 -- @class function
 -- @name quit
 local quit
 
 ---
--- Resets the Lua state by reloading all init scripts.
+-- Resets the Lua state by reloading all initialization scripts.
 -- Language-specific modules for opened files are NOT reloaded. Re-opening the
 -- files that use them will reload those modules instead.
 -- This function is useful for modifying user scripts (such as
@@ -125,9 +132,9 @@ local quit
 local reset
 
 ---
--- Calls a given function after an interval of time.
--- To repeatedly call the function, return `true` inside the function. A `nil`
--- or `false` return value stops repetition.
+-- Calls the function *f* with the given arguments after *interval* seconds and
+-- then repeatedly while *f* returns `true`. A `nil` or `false` return value
+-- stops repetition.
 -- @param interval The interval in seconds to call the function after.
 -- @param f The function to call.
 -- @param ... Additional arguments to pass to `f`.
diff --git a/core/keys.lua b/core/keys.lua
index ba1df7b4..7d2b06a0 100644
--- a/core/keys.lua
+++ b/core/keys.lua
@@ -83,9 +83,9 @@ local M = {}
 --   The default value is `'esc'` for the `Esc` (`⎋` on Mac OSX | `Esc` in
 --   ncurses) key.
 -- @field LANGUAGE_MODULE_PREFIX (string)
---   The starting key command of the key chain reserved for language-specific
---   modules.
---   The default value is `Ctrl+L` (`⌘L` on Mac OSX | `M-L` in ncurses).
+--   The starting key of the key chain reserved for language-specific modules.
+--   The default value is `'cl'` on platforms other than Mac OSX, `'ml'`
+--   otherwise. Equivalent to `Ctrl+L` (`⌘L` on Mac OSX | `M-L` in ncurses).
 module('keys')]]
 
 local ADD = ''
@@ -107,7 +107,7 @@ local error = function(e) events.emit(events.ERROR, e) end
 ---
 -- Lookup table for string representations of key codes higher than 255.
 -- Key codes can be identified by temporarily uncommenting the `print()`
--- statements in *core/keys.lua*
+-- statements in *core/keys.lua*.
 -- @class table
 -- @name KEYSYMS
 M.KEYSYMS = {
@@ -282,4 +282,11 @@ local function get_gdk_key(key_seq)
 end
 M.get_gdk_key = get_gdk_key -- export for menu.lua without generating LuaDoc
 
+---
+-- Map of key bindings to commands, with language-specific key tables assigned
+-- to a lexer name key.
+-- @class table
+-- @name _G.keys
+local keys
+
 return M
diff --git a/core/locale.lua b/core/locale.lua
index 715e817e..87123183 100644
--- a/core/locale.lua
+++ b/core/locale.lua
@@ -4,7 +4,7 @@ local M = {}
 
 --[[ This comment is for LuaDoc.
 ---
--- Table of all messages used by Textadept for localization.
+-- Map of all messages used by Textadept to their localized form.
 -- If the table does not contain the localized version of a given message, it
 -- returns a string indicating so via a metamethod.
 module('_L')]]
@@ -12,10 +12,11 @@ module('_L')]]
 local none = 'No Localization: '
 
 ---
--- Returns whether or not a localized message exists for the given message.
+-- Returns whether or not *message* is localized.
 -- This function is necessary since `_L[message]` never returns `nil`.
 -- @param message The message to localize.
 -- @return `true` if a localization exists, `false` otherwise.
+-- @name _EXISTS
 function M._EXISTS(message) return M[message] ~= none..message end
 
 local f = io.open(_USERHOME..'/locale.conf', 'rb')