Revert "Revert "Merge remote-tracking branch 'origin/sandbox/mniesluchow/upstream_2_1...

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

diff --git a/atk/atkhypertext.c b/atk/atkhypertext.c
index cfca58e..984899a 100755 (executable)
--- a/atk/atkhypertext.c
+++ b/atk/atkhypertext.c
@@ -1,5 +1,5 @@
 /* ATK - The Accessibility Toolkit for GTK+
- * Copyright 2001 Sun Microsystems Inc.
+ * Copyright 2001, 2002, 2003 Sun Microsystems Inc.
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Library General Public
@@ -17,8 +17,26 @@
  * Boston, MA 02111-1307, USA.
  */
 
+#include "config.h"
+
 #include "atkhypertext.h"
 
+/**
+ * SECTION:atkhypertext
+ * @Short_description: The ATK interface which provides standard
+ *  mechanism for manipulating hyperlinks.
+ * @Title:AtkHypertext
+ *
+ * An interface used for objects which implement linking between
+ * multiple resource or content locations, or multiple 'markers'
+ * within a single document.  A Hypertext instance is associated with
+ * one or more Hyperlinks, which are associated with particular
+ * offsets within the Hypertext's included content.  While this
+ * interface is derived from Text, there is no requirement that
+ * Hypertext instances have textual content; they may implement Image
+ * as well, and Hyperlinks need not have non-zero text offsets.
+ */
+
 enum {
   LINK_SELECTED,
   LAST_SIGNAL
@@ -30,7 +48,7 @@ static guint atk_hypertext_signals[LAST_SIGNAL] = { 0 };
 
 
 GType
-atk_hypertext_get_type ()
+atk_hypertext_get_type (void)
 {
   static GType type = 0;
 
@@ -56,6 +74,15 @@ atk_hypertext_base_init (AtkHypertextIface *class)
 
   if (!initialized)
     {
+      /**
+       * AtkHypertext::link-selected:
+       * @atkhypertext: the object which received the signal.
+       * @arg1: the index of the hyperlink which is selected
+       *
+       * The "link-selected" signal is emitted by an AtkHyperText
+       * object when one of the hyperlinks associated with the object
+       * is selected.
+       */
       atk_hypertext_signals[LINK_SELECTED] =
         g_signal_new ("link_selected",
                       ATK_TYPE_HYPERTEXT,
@@ -78,7 +105,7 @@ atk_hypertext_base_init (AtkHypertextIface *class)
  * Gets the link in this hypertext document at index 
  * @link_index
  *
- * Returns: the link in this hypertext document at
+ * Returns: (transfer none): the link in this hypertext document at
  * index @link_index
  **/
 AtkHyperlink* 
@@ -89,6 +116,9 @@ atk_hypertext_get_link (AtkHypertext  *hypertext,
 
   g_return_val_if_fail (ATK_IS_HYPERTEXT (hypertext), NULL);
 
+  if (link_index < 0)
+    return NULL;
+
   iface = ATK_HYPERTEXT_GET_IFACE (hypertext);
 
   if (iface->get_link)
@@ -126,10 +156,10 @@ atk_hypertext_get_n_links (AtkHypertext  *hypertext)
  * @char_index: a character index
  *
  * Gets the index into the array of hyperlinks that is associated with
- * the character specified by @char_index, or -1 if there is no hyperlink
- * associated with this character.
+ * the character specified by @char_index.
  *
- * Returns: an index into the array of hyperlinks in @hypertext
+ * Returns: an index into the array of hyperlinks in @hypertext,
+ * or -1 if there is no hyperlink associated with this character.
  **/
 gint 
 atk_hypertext_get_link_index (AtkHypertext  *hypertext,
@@ -139,6 +169,9 @@ atk_hypertext_get_link_index (AtkHypertext  *hypertext,
 
   g_return_val_if_fail (ATK_IS_HYPERTEXT (hypertext), -1);
 
+  if (char_index < 0)
+    return -1;
+
   iface = ATK_HYPERTEXT_GET_IFACE (hypertext);
 
   if (iface->get_link_index)