Add .gbs.conf to track remote git properly

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

diff --git a/atk/atkhyperlinkimpl.c b/atk/atkhyperlinkimpl.c
index e4ad10f..bdfe6c1 100644 (file)
--- a/atk/atkhyperlinkimpl.c
+++ b/atk/atkhyperlinkimpl.c
@@ -20,6 +20,42 @@
 #include <string.h>
 #include "atkhyperlinkimpl.h"
 
+/**
+ * SECTION:atkhyperlinkimpl
+ * @Short_description: An interface from which the AtkHyperlink
+ *  associated with an AtkObject may be obtained.
+ * @Title:AtkHyperlinImpl
+ *
+ * AtkHyperlinkImpl allows AtkObjects to refer to their associated
+ * AtkHyperlink instance, if one exists.  AtkHyperlinkImpl differs
+ * from AtkHyperlink in that AtkHyperlinkImpl is an interface, whereas
+ * AtkHyperlink is a object type.  The AtkHyperlinkImpl interface
+ * allows a client to query an AtkObject for the availability of an
+ * associated AtkHyperlink instance, and obtain that instance.  It is
+ * thus particularly useful in cases where embedded content or inline
+ * content within a text object is present, since the embedding text
+ * object implements AtkHypertext and the inline/embedded objects are
+ * exposed as children which implement AtkHyperlinkImpl, in addition
+ * to their being obtainable via AtkHypertext:getLink followed by
+ * AtkHyperlink:getObject.
+ *
+ * The AtkHyperlinkImpl interface should be supported by objects
+ * exposed within the hierarchy as children of an AtkHypertext
+ * container which correspond to "links" or embedded content within
+ * the text.  HTML anchors are not, for instance, normally exposed
+ * this way, but embedded images and components which appear inline in
+ * the content of a text object are. The AtkHyperlinkIface interface
+ * allows a means of determining which children are hyperlinks in this
+ * sense of the word, and for obtaining their corresponding
+ * AtkHyperlink object, from which the embedding range, URI, etc. can
+ * be obtained.
+ *
+ * To some extent this interface exists because, for historical
+ * reasons, AtkHyperlink was defined as an object type, not an
+ * interface.  Thus, in order to interact with AtkObjects via
+ * AtkHyperlink semantics, a new interface was required.
+ */
+
 GType
 atk_hyperlink_impl_get_type (void)
 {