meson: Add atkversion.h to introspection build

[platform/upstream/atk.git] / atk / atkselection.c

diff --git a/atk/atkselection.c b/atk/atkselection.c
old mode 100755 (executable)
new mode 100644 (file)
index 4088fa8..d4bd836
--- a/atk/atkselection.c
+++ b/atk/atkselection.c
@@ -17,8 +17,29 @@
  * Boston, MA 02111-1307, USA.
  */
 
+#include "config.h"
+
 #include "atkselection.h"
 
+/**
+ * SECTION:atkselection
+ * @Short_description: The ATK interface implemented by container
+ *  objects whose #AtkObject children can be selected.
+ * @Title:AtkSelection
+ *
+ * #AtkSelection should be implemented by UI components with children
+ * which are exposed by #atk_object_ref_child and
+ * #atk_object_get_n_children, if the use of the parent UI component
+ * ordinarily involves selection of one or more of the objects
+ * corresponding to those #AtkObject children - for example,
+ * selectable lists.
+ *
+ * Note that other types of "selection" (for instance text selection)
+ * are accomplished a other ATK interfaces - #AtkSelection is limited
+ * to the selection/deselection of children.
+ */
+
+
 enum {
   SELECTION_CHANGED,
   LAST_SIGNAL
@@ -55,6 +76,13 @@ atk_selection_base_init (gpointer *g_class)
 
   if (! initialized)
     {
+      /**
+       * AtkSelection::selection-changed:
+       * @atkselection: the object which received the signal.
+       *
+       * The "selection-changed" signal is emitted by an object which
+       * implements AtkSelection interface when the selection changes.
+       */
       atk_selection_signals[SELECTION_CHANGED] =
         g_signal_new ("selection_changed",
                       ATK_TYPE_SELECTION,
@@ -132,8 +160,9 @@ atk_selection_clear_selection (AtkSelection *obj)
  * use type checking/interface checking macros or the
  * atk_get_accessible_value() convenience method.
  *
- * Returns: an #AtkObject representing the selected accessible , or %NULL
- * if @selection does not implement this interface.
+ * Returns: (nullable) (transfer full): an #AtkObject representing the
+ * selected accessible, or %NULL if @selection does not implement this
+ * interface.
  **/
 AtkObject*
 atk_selection_ref_selection (AtkSelection *obj,