Updated documentation on rearranging tabs and `move_buffer()`.

4 files changed, 15 insertions, 5 deletions

diff --git a/core/init.lua b/core/init.lua
index 56b7519f..aebc7da9 100644
--- a/core/init.lua
+++ b/core/init.lua
@@ -134,9 +134,12 @@ local view
 -- The functions below are Lua C functions.
 
 ---
--- Moves the buffer at index *from* to index *to*, shifting other buffers as necessary.
+-- Moves the buffer at index *from* to index *to* in the `_BUFFERS` table, shifting other buffers
+-- as necessary.
+-- This changes the order buffers are displayed in in the tab bar and buffer browser.
 -- @param from Index of the buffer to move.
 -- @param to Index to move the buffer to.
+-- @see _BUFFERS
 -- @class function
 -- @name move_buffer
 local move_buffer
diff --git a/docs/api.md b/docs/api.md
index 2c98084c..acbacf4c 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -101,13 +101,19 @@ The path to the user's *~/.textadept/* directory, where all preferences and user
 <a id="move_buffer"></a>
 #### `move_buffer`(*from, to*)
 
-Moves the buffer at index *from* to index *to*, shifting other buffers as necessary.
+Moves the buffer at index *from* to index *to* in the `_BUFFERS` table, shifting other buffers
+as necessary.
+This changes the order buffers are displayed in in the tab bar and buffer browser.
 
 Parameters:
 
 * *`from`*: Index of the buffer to move.
 * *`to`*: Index to move the buffer to.
 
+See also:
+
+* [`_BUFFERS`](#_BUFFERS)
+
 <a id="quit"></a>
 #### `quit`()
 
diff --git a/docs/manual.md b/docs/manual.md
index 1aca3d02..b15ca9d7 100644
--- a/docs/manual.md
+++ b/docs/manual.md
@@ -385,8 +385,9 @@ indicates there are unsaved changes in the marked buffer. There is only one tab
 entire application, even if there are multiple split views. When two or more views are open, the
 state of the tab bar applies only to the active view, and using the tab bar to switch between
 files also applies only to that view. Right-clicking on the tab bar brings up a configurable
-context menu that is defined by [`textadept.menu.tab_context_menu`][]. You can turn off the
-tab bar by setting [`ui.tabs`][]. For example, in your *~/.textadept/init.lua*:
+context menu that is defined by [`textadept.menu.tab_context_menu`][]. Tabs can be rearranged
+by clicking on their tops and dragging and dropping them. You can turn off the tab bar by setting
+[`ui.tabs`][]. For example, in your *~/.textadept/init.lua*:
 
     ui.tabs = false
 
diff --git a/modules/lua/ta_api b/modules/lua/ta_api
index 000ca551..0c573536 100644
--- a/modules/lua/ta_api
+++ b/modules/lua/ta_api
@@ -728,7 +728,7 @@ modify buffer.modify (bool, Read-only)\nWhether or not the buffer has unsaved ch
 modify_rule lexer.modify_rule(lexer, id, rule)\nReplaces in lexer *lexer* the existing rule identified by string *id* with pattern *rule*.\n@param lexer The lexer to modify.\n@param id The id associated with this rule.\n@param rule The LPeg pattern of the rule.
 mouse_dwell_time view.mouse_dwell_time (number)\nThe number of milliseconds the mouse must idle before generating a `DWELL_START` event. A\ntime of `view.TIME_FOREVER` will never generate one.
 mouse_selection_rectangular_switch view.mouse_selection_rectangular_switch (bool)\nWhether or not pressing `view.rectangular_selection_modifier` when selecting text\nnormally with the mouse turns on rectangular selection.\nThe default value is `false`.
-move_buffer _G.move_buffer(from, to)\nMoves the buffer at index *from* to index *to*, shifting other buffers as necessary.\n@param from Index of the buffer to move.\n@param to Index to move the buffer to.
+move_buffer _G.move_buffer(from, to)\nMoves the buffer at index *from* to index *to* in the `_BUFFERS` table, shifting other buffers\nas necessary.\nThis changes the order buffers are displayed in in the tab bar and buffer browser.\n@param from Index of the buffer to move.\n@param to Index to move the buffer to.\n@see _BUFFERS
 move_caret_inside_view buffer.move_caret_inside_view(buffer)\nMoves the caret into view if it is not already, removing any selections.\n@param buffer A buffer.
 move_extends_selection buffer.move_extends_selection (bool, Read-only)\nWhether or not regular caret movement alters the selected text.\n`buffer.selection_mode` dictates this property.
 move_selected_lines_down buffer.move_selected_lines_down(buffer)\nShifts the selected lines down one line.\n@param buffer A buffer.