[atk] Fix for bug 668441 - atk_action_get_keybinding() docs are confusing and need updating

[Alejandro PiÃeiro Iglesias <apinheiro src gnome org>]

commit c347f165518cc4afef8c3f4f42a2722d99725c47
Author: Joanmarie Diggs <jdiggs igalia com>
Date:   Sun Jan 22 20:47:23 2012 +0100

    Fix for bug 668441 - atk_action_get_keybinding() docs are confusing and need updating

 atk/atkaction.c |   41 ++++++++++++++++++++++++++---------------
 1 files changed, 26 insertions(+), 15 deletions(-)
---
diff --git a/atk/atkaction.c b/atk/atkaction.c
index b37ebc9..fe27eb1 100755
--- a/atk/atkaction.c
+++ b/atk/atkaction.c
@@ -185,21 +185,32 @@ atk_action_get_localized_name (AtkAction *obj,
 /**
  * atk_action_get_keybinding:
  * @action: a #GObject instance that implements AtkActionIface
- * @i: the action index corresponding to the action to be performed 
+ * @i: the action index corresponding to the action to be performed
+ *
+ * Gets the keybinding which can be used to activate this action, if one
+ * exists. The string returned should contain localized, human-readable,
+ * key sequences as they would appear when displayed on screen. It must
+ * be in the format "mnemonic;sequence;shortcut".
+ *
+ * - The mnemonic key activates the object if it is presently enabled onscreen.
+ *   This typically corresponds to the underlined letter within the widget.
+ *   Example: "n" in a traditional "New..." menu item or the "a" in "Apply" for
+ *   a button.
+ * - The sequence is the full list of keys which invoke the action even if the
+ *   relevant element is not currently shown on screen. For instance, for a menu
+ *   item the sequence is the keybindings used to open the parent menus before
+ *   invoking. The sequence string is colon-delimited. Example: "Alt+F:N" in a
+ *   traditional "New..." menu item.
+ * - The shortcut, if it exists, will invoke the same action without showing
+ *   the component or its enclosing menus or dialogs. Example: "Ctrl+N" in a
+ *   traditional "New..." menu item.
+ *
+ * Example: For a traditional "New..." menu item, the expected return value
+ * would be: "N;Alt+F:N;Ctrl+N" for the English locale and "N;Alt+D:N;Strg+N"
+ * for the German locale. If, hypothetically, this menu item lacked a mnemonic,
+ * it would be represented by ";;Ctrl+N" and ";;Strg+N" respectively.
  *
- * Returns a keybinding associated with this action, if one exists.
- * The returned string is in the format "<a>;<b>;<c>"
- * (i.e. semicolon-delimited), where <a> is the keybinding which
- * activates the object if it is presently enabled onscreen, 
- * <b> corresponds to the keybinding or sequence of keys
- * which invokes the action even if the relevant element is not
- * currently posted on screen (for instance, for a menu item it
- * posts the parent menus before invoking).  The last token in the
- * above string, if non-empty, represents a keyboard shortcut which
- * invokes the same action without posting the component or its
- * enclosing menus or dialogs. 
- *
- * Returns a string representing the available keybindings, or %NULL
+ * Returns the keybinding which can be used to activate this action, or %NULL
  * if there is no keybinding for this action.
  *
  **/