From bfa7b0af02a6ec66898723fe3e82f74760996a10 Mon Sep 17 00:00:00 2001
From: Nathan Willis <nwillis@glyphography.com>
Date: Mon, 20 May 2019 17:36:55 +0100
Subject: [PATCH] [Docs] Add gtk-doc comments to hb-gobject and hb-glib.

---
 src/hb-glib.cc            | 44 ++++++++++++++++++++++++++++++++++++++-
 src/hb-gobject-structs.cc | 13 ++++++++++--
 2 files changed, 54 insertions(+), 3 deletions(-)

diff --git a/src/hb-glib.cc b/src/hb-glib.cc
index 576375460..b441efe0e 100644
--- a/src/hb-glib.cc
+++ b/src/hb-glib.cc
@@ -39,7 +39,11 @@
  * @short_description: GLib integration
  * @include: hb-glib.h
  *
- * Functions for using HarfBuzz with the GLib library to provide Unicode data.
+ * Functions for using HarfBuzz with the GLib library. 
+ *
+ * HarfBuzz supports using GLib to provide Unicode data, by attaching
+ * GLib functions to the virtual methods in a #hb_unicode_funcs_t function
+ * structure.
  **/
 
 
@@ -167,6 +171,17 @@ glib_script_to_script[] =
 };
 #endif
 
+/**
+ * hb_glib_script_to_script:
+ * @script: The GUnicodeScript identifier to query
+ *
+ * Fetches the #hb_script_t script that corresponds to the
+ * specified GUnicodeScript identifier.
+ *
+ * Return value: the #hb_script_t script found
+ *
+ * Since: 0.9.38
+ **/
 hb_script_t
 hb_glib_script_to_script (GUnicodeScript script)
 {
@@ -183,6 +198,17 @@ hb_glib_script_to_script (GUnicodeScript script)
 #endif
 }
 
+/**
+ * hb_glib_script_from_script:
+ * @script: The #hb_script_t to query
+ *
+ * Fetches the GUnicodeScript identifier that corresponds to the
+ * specified #hb_script_t script.
+ *
+ * Return value: the GUnicodeScript identifier found
+ *
+ * Since: 0.9.38
+ **/
 GUnicodeScript
 hb_glib_script_from_script (hb_script_t script)
 {
@@ -371,6 +397,16 @@ void free_static_glib_funcs ()
 }
 #endif
 
+/**
+ * hb_glib_get_unicode_funcs:
+ *
+ * Fetches a Unicode-functions structure that is populated
+ * with the appropriate GLib function for each method.
+ *
+ * Return value: (transfer full): a pointer to the #hb_unicode_funcs_t Unicode-functions structure
+ *
+ * Since: 0.9.38
+ **/
 hb_unicode_funcs_t *
 hb_glib_get_unicode_funcs ()
 {
@@ -389,6 +425,12 @@ _hb_g_bytes_unref (void *data)
 
 /**
  * hb_glib_blob_create:
+ * @gbytes: the GBytes structure to work upon
+ *
+ * Creates an #hb_blob_t blob from the specified
+ * GBytes data structure.
+ *
+ * Return value: (transfer full): the new #hb_blob_t blob object
  *
  * Since: 0.9.38
  **/
diff --git a/src/hb-gobject-structs.cc b/src/hb-gobject-structs.cc
index 3cff880aa..b91bbb416 100644
--- a/src/hb-gobject-structs.cc
+++ b/src/hb-gobject-structs.cc
@@ -30,11 +30,20 @@
 /**
  * SECTION:hb-gobject
  * @title: hb-gobject
- * @short_description: GObject integration
+ * @short_description: GObject integration support
  * @include: hb-gobject.h
  *
- * Functions for using HarfBuzz with the GObject library to provide
+ * Support for using HarfBuzz with the GObject library to provide
  * type data.
+ *
+ * The types and functions listed here are solely a linkage between
+ * HarfBuzz's public data types and the GTypes used by the GObject framework.
+ * HarfBuzz uses GObject introspection to generate its Python bindings 
+ * (and potentially other language bindings); client programs should never need
+ * to access the GObject-integration mechanics.
+ *
+ * For client programs using the GNOME and GTK software stack, please see the
+ * GLib and FreeType integration pages.
  **/