[atk: 1/2] Update documentation for atk_text_set_caret_offset.

[Joanmarie Diggs <joanied src gnome org>]

commit f7306bcc888c5f0a8793598b3928b52490d69c32
Author: Joanmarie Diggs <jdiggs igalia com>
Date:   Wed Jan 15 13:38:49 2020 +0000

    Update documentation for atk_text_set_caret_offset.
    
    The documentation lacked any mention of scrolling content into view
    when the specified content is off-screen.

 atk/atktext.c | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)
---
diff --git a/atk/atktext.c b/atk/atktext.c
index b85d93f..3728bd4 100644
--- a/atk/atktext.c
+++ b/atk/atktext.c
@@ -1031,6 +1031,22 @@ atk_text_set_selection (AtkText *text,
  *
  * Sets the caret (cursor) position to the specified @offset.
  *
+ * In the case of rich-text content, this method should either grab focus
+ * or move the sequential focus navigation starting point (if the application
+ * supports this concept) as if the user had clicked on the new caret position.
+ * Typically, this means that the target of this operation is the node containing
+ * the new caret position or one of its ancestors. In other words, after this
+ * method is called, if the user advances focus, it should move to the first
+ * focusable node following the new caret position.
+ *
+ * Calling this method should also scroll the application viewport in a way
+ * that matches the behavior of the application's typical caret motion or tab
+ * navigation as closely as possible. This also means that if the application's
+ * caret motion or focus navigation does not trigger a scroll operation, this
+ * method should not trigger one either. If the application does not have a caret
+ * motion or focus navigation operation, this method should try to scroll the new
+ * caret position into view while minimizing unnecessary scroll motion.
+ *
  * Returns: %TRUE if successful, %FALSE otherwise.
  **/
 gboolean