Added improved comments (from Oisin), fixed a couple of minor bugs.

Tried to rationalize the interface, changed some return types and signatures
(get_uri instead of get_anchor, returns char*).  Added method to
return how many anchors are present (for client-side imagemaps).

2 files changed, 71 insertions, 60 deletions

diff --git a/atk/atkhyperlink.c b/atk/atkhyperlink.c
index b8fdfc2..1ebf04e 100755
--- a/atk/atkhyperlink.c
+++ b/atk/atkhyperlink.c
@@ -75,19 +75,20 @@ atk_hyperlink_init  (AtkHyperlink        *link,
 }
 
 /**
- *atk_hyperlink_get_anchor:
- *@link: an #AtkHyperlink
- *@i:
+ * atk_hyperlink_get_uri:
+ * @link: an #AtkHyperlink
+ * @i: a (zero-index) integer specifying the desired anchor
  *
- * Returns an object which represents the link anchor, as appropriate for 
- * that link.
+ * Get a the URI associated with the anchor specified 
+ * by @i of @link. 
  *
- * Returns: an object which represents the link anchor, as appropriate for 
- * that link.
+ * Multiple anchors are primarily used by client-side image maps.
+ *
+ * Returns: a string specifying the URI 
  **/
-GObject*
-atk_hyperlink_get_anchor (AtkHyperlink *link,
-                          gint         i)
+gchar*
+atk_hyperlink_get_uri (AtkHyperlink *link,
+                       gint         i)
 {
   AtkHyperlinkClass *klass;
 
@@ -95,23 +96,25 @@ atk_hyperlink_get_anchor (AtkHyperlink *link,
   g_return_val_if_fail (ATK_IS_HYPERLINK (link), NULL);
 
   klass = ATK_HYPERLINK_GET_CLASS (link);
-  g_return_val_if_fail ((klass->get_anchor != NULL), NULL);
+  g_return_val_if_fail ((klass->get_uri != NULL), NULL);
 
-  return (klass->get_anchor) (link, i);
+  return (klass->get_uri) (link, i);
 }
 
 /**
- *atk_hyperlink_get_object:
- *@link: an #AtkHyperlink
- *@i:
+ * atk_hyperlink_get_object:
+ * @link: an #AtkHyperlink
+ * @i: a (zero-index) integer specifying the desired anchor
  *
- * Returns an object which represents the link action, as appropriate for 
- * that link.
+ * Returns the item associated with this hyperlinks nth anchor. For instance,
+ * the returned #AtkObject will implement #AtkText if @link is a text hyperlink, 
+ * #AtkImage if @link is an image hyperlink etc. 
+ * 
+ * Multiple anchors are primarily used by client-side image maps.
  *
- * Returns: an object which represents the link action, as appropriate for 
- * that link.
+ * Returns: an #AtkObject associated with this hyperlinks i-th anchor.
  **/
-GObject*
+AtkObject*
 atk_hyperlink_get_object (AtkHyperlink *link,
                           gint         i)
 {
@@ -127,32 +130,12 @@ atk_hyperlink_get_object (AtkHyperlink *link,
 }
 
 /**
- *atk_hyperlink_get_end_actions:
- *@link: an #AtkHyperlink
- *
- *
- **/
-//gint
-//atk_hyperlink_get_end_actions (AtkHyperlink *link)
-//{
-//  AtkHyperlinkClass *klass;
-//
-//  g_return_val_if_fail ((link != NULL), 0);
-//  g_return_val_if_fail (ATK_IS_HYPERLINK (link), 0);
-//
-//  klass = ATK_HYPERLINK_GET_CLASS (link);
-//  g_return_val_if_fail ((klass->get_end_index != NULL), 0);
-//
-//  return (klass->get_end_index) (link);
-//}
-
-/**
- *atk_hyperlink_get_end_index:
- *@link: an #AtkHyperlink
+ * atk_hyperlink_get_end_index:
+ * @link: an #AtkHyperlink
  *
  * Gets the index with the hypertext document at which this link ends
  *
- *Returns: the index with the hypertext document at which this link ends
+ * Returns: the index with the hypertext document at which this link ends
  **/
 gint
 atk_hyperlink_get_end_index (AtkHyperlink *link)
@@ -169,12 +152,12 @@ atk_hyperlink_get_end_index (AtkHyperlink *link)
 }
 
 /**
- *atk_hyperlink_get_start_index:
- *@link: an #AtkHyperlink
+ * atk_hyperlink_get_start_index:
+ * @link: an #AtkHyperlink
  *
  * Gets the index with the hypertext document at which this link begins 
  *
- *Returns: the index with the hypertext document at which this link begins
+ * Returns: the index with the hypertext document at which this link begins
  **/
 gint
 atk_hyperlink_get_start_index (AtkHyperlink *link)
@@ -187,21 +170,21 @@ atk_hyperlink_get_start_index (AtkHyperlink *link)
   klass = ATK_HYPERLINK_GET_CLASS (link);
   g_return_val_if_fail ((klass->get_start_index != NULL), 0);
 
-  return (klass->get_end_index) (link);
+  return (klass->get_start_index) (link);
 }
 
 /**
- *atk_hyperlink_is_valid:
- *@link: an #AtkHyperlink
+ * atk_hyperlink_is_valid:
+ * @link: an #AtkHyperlink
  *
  * Since the document a link is associated with may have changed, this 
  * method returns whether or not this link is still valid (with respect
  * to the document is references)
  *
- *Returns: whether or not this link is still valid.
+ * Returns: whether or not this link is still valid.
  **/
 gboolean
-atk_hyperlink_get_valid (AtkHyperlink *link)
+atk_hyperlink_is_valid (AtkHyperlink *link)
 {
   AtkHyperlinkClass *klass;
 
@@ -214,6 +197,28 @@ atk_hyperlink_get_valid (AtkHyperlink *link)
   return (klass->is_valid) (link);
 }
 
+/**
+ * atk_hyperlink_get_n_anchors:
+ * @link: an #AtkHyperlink
+ *
+ * Gets the number of anchors associated with this hyperlink
+ *
+ * Returns: the number of anchors associated with this hyperlink
+ **/
+gint
+atk_hyperlink_get_n_anchors (AtkHyperlink *link)
+{
+  AtkHyperlinkClass *klass;
+
+  g_return_val_if_fail ((link != NULL), 0);
+  g_return_val_if_fail (ATK_IS_HYPERLINK (link), 0);
+
+  klass = ATK_HYPERLINK_GET_CLASS (link);
+  g_return_val_if_fail ((klass->get_n_anchors != NULL), 0);
+
+  return (klass->get_n_anchors) (link);
+}
+
 static void atk_hyperlink_action_iface_init (AtkActionIface *iface)
 {
   /*
diff --git a/atk/atkhyperlink.h b/atk/atkhyperlink.h
index eee141d..b2dbaac 100755
--- a/atk/atkhyperlink.h
+++ b/atk/atkhyperlink.h
@@ -52,50 +52,56 @@ struct _AtkHyperlinkClass
   GObjectClass parent;
 
   /*
-   * Returns an object which represents the link anchor, as appropriate for 
-   * that link.
+   * Returns a string specifying the URI associated with the nth anchor
+   * of this link.
    */
-  GObject*         (* get_anchor)          (AtkHyperlink     *link,
+  gchar*           (* get_uri)             (AtkHyperlink     *link,
                                             gint             i);
   /*
    * Returns an object which represents the link action, as appropriate for 
    * that link.
    */
-  GObject*         (* get_object)          (AtkHyperlink     *link,
+  AtkObject*       (* get_object)          (AtkHyperlink     *link,
                                             gint             i);
-  //gint	     (* get_end_actions)     (AtkHyperlink     *link);
   /*
    * Gets the index with the hypertext document at which this link ends
    */
   gint             (* get_end_index)       (AtkHyperlink     *link);
+
   /* 
    * Gets the index with the hypertext document at which this link begins 
    */
   gint             (* get_start_index)     (AtkHyperlink     *link);
+
   /*
    * Since the document a link is associated with may have changed, this 
    * method returns whether or not this link is still valid (with respect
    * to the document is references)
    */
   gboolean         (* is_valid)            (AtkHyperlink     *link);
+
+  /* 
+   * Returns the number of anchors associated with this link
+   */
+  gint	           (* get_n_anchors)	   (AtkHyperlink     *link);
 };
 
 GType            atk_hyperlink_get_type             (void);
 
-GObject*         atk_hyperlink_get_anchor           (AtkHyperlink     *link,
+gchar*           atk_hyperlink_get_uri              (AtkHyperlink     *link,
                                                      gint             i);
 
-GObject*         atk_hyperlink_get_object           (AtkHyperlink     *link,
+AtkObject*       atk_hyperlink_get_object           (AtkHyperlink     *link,
                                                      gint             i);
 
 gint             atk_hyperlink_get_end_index        (AtkHyperlink     *link);
 
-//gint             atk_hyperlink_get_end_actions        (AtkHyperlink     *link);
-
 gint             atk_hyperlink_get_start_index      (AtkHyperlink     *link);
 
 gboolean         atk_hyperlink_is_valid             (AtkHyperlink     *link);
 
+gint		 atk_hyperlink_get_n_anchors        (AtkHyperlink     *link);
+
 
 #ifdef __cplusplus
 }