From 7e7a33dc3e56501981a721bfa18ffd5f21e0acc1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Wiktor=20Obr=C4=99bski?= <psychowico@gmail.com>
Date: Thu, 21 Nov 2024 21:39:33 +0100
Subject: [PATCH] Improve TextArea documentation

---
 docs/dev/Lua API.rst | 21 ++++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst
index ebe4fc6c84..5852a18d8e 100644
--- a/docs/dev/Lua API.rst	
+++ b/docs/dev/Lua API.rst	
@@ -5589,14 +5589,29 @@ TextArea Functions:
 * ``textarea:scrollToCursor()``
 
     Scrolls the text area view to ensure that the current cursor position is visible.
-    This is useful for automatically scrolling when the user moves the cursor
-    beyond the visible region of the text area.
+    This happens automatically when the user interactively moves the cursor or
+    pastes text into the widget, but may need to be called when ``setCursor`` is
+    called programmatically.
 
 * ``textarea:clearHistory()``
 
     Clear undo/redo history of the widget.
 
-Functionality:
+Functionality
+-------------
+
+The TextArea widget provides a familiar and intuitive text editing experience with baseline features such as:
+
+- Text Wrapping: Automatically fits text within the display area.
+- Mouse and Keyboard Support: Standard keys like :kbd:`Home`, :kbd:`End`, :kbd:`Backspace`, and :kbd:`Delete` are supported,
+    along with gestures like double-click to select a word or triple-click to select a line.
+- Clipboard Operations: copy, cut, and paste,
+    with intuitive defaults when no text is selected.
+- Undo/Redo: :kbd:`Ctrl` + :kbd:`Z` and :kbd:`Ctrl` + :kbd:`Y` for quick changes.
+- Additional features include advanced navigation, line management,
+    and smooth scrolling for handling long text efficiently.
+
+Detailed list:
 
 - Cursor Control: Navigate through text using arrow keys (Left, Right, Up,
     and Down) for precise cursor placement.