Add a lot of Gtk-Doc markup and generate a valid GIR file

17 files changed, 866 insertions, 88 deletions

diff --git a/libappstream-glib/Makefile.am b/libappstream-glib/Makefile.am
index fb91242..9b4835b 100644
--- a/libappstream-glib/Makefile.am
+++ b/libappstream-glib/Makefile.am
@@ -71,19 +71,20 @@ TESTS = as-self-test
 
 if HAVE_INTROSPECTION
 introspection_sources =						\
-	$(libappstream_glib_la_SOURCES)	
+	$(libappstream_glib_include_HEADERS)			\
+	$(libappstream_glib_la_SOURCES)
 
-AppStream-1.0.gir: libappstream-glib.la
-AppStream_1_0_gir_INCLUDES = GObject-2.0 Gio-2.0
-AppStream_1_0_gir_CFLAGS = $(AM_CPPFLAGS)
-AppStream_1_0_gir_SCANNERFLAGS = --identifier-prefix=As \
+AppStreamGlib-1.0.gir: libappstream-glib.la
+AppStreamGlib_1_0_gir_INCLUDES = GObject-2.0 Gio-2.0
+AppStreamGlib_1_0_gir_CFLAGS = $(AM_CPPFLAGS)
+AppStreamGlib_1_0_gir_SCANNERFLAGS = --identifier-prefix=As \
 				--symbol-prefix=as_ \
 				--warn-all \
 				--add-include-path=$(srcdir)
-AppStream_1_0_gir_EXPORT_PACKAGES = appstream-glib
-AppStream_1_0_gir_LIBS = libappstream-glib.la
-AppStream_1_0_gir_FILES = $(introspection_sources)
-INTROSPECTION_GIRS += AppStream-1.0.gir
+AppStreamGlib_1_0_gir_EXPORT_PACKAGES = appstream-glib
+AppStreamGlib_1_0_gir_LIBS = libappstream-glib.la
+AppStreamGlib_1_0_gir_FILES = $(introspection_sources)
+INTROSPECTION_GIRS += AppStreamGlib-1.0.gir
 
 girdir = $(datadir)/gir-1.0
 gir_DATA = $(INTROSPECTION_GIRS)
diff --git a/libappstream-glib/as-app.c b/libappstream-glib/as-app.c
index 5bba3fa..f746657 100644
--- a/libappstream-glib/as-app.c
+++ b/libappstream-glib/as-app.c
@@ -100,7 +100,7 @@ as_app_finalize (GObject *object)
 
 /**
  * as_app_token_item_free:
- */
+ **/
 static void
 as_app_token_item_free (AsAppTokenItem *token_item)
 {
@@ -145,6 +145,13 @@ as_app_class_init (AsAppClass *klass)
 
 /**
  * as_app_id_kind_to_string:
+ * @id_kind: the #AsAppIdKind.
+ *
+ * Converts the enumerated value to an text representation.
+ *
+ * Returns: string version of @id_kind
+ *
+ * Since: 0.1.0
  **/
 const gchar *
 as_app_id_kind_to_string (AsAppIdKind id_kind)
@@ -166,6 +173,13 @@ as_app_id_kind_to_string (AsAppIdKind id_kind)
 
 /**
  * as_app_id_kind_from_string:
+ * @id_kind: the string.
+ *
+ * Converts the text representation to an enumerated value.
+ *
+ * Returns: a #AsAppIdKind or %AS_APP_ID_KIND_UNKNOWN for unknown
+ *
+ * Since: 0.1.0
  **/
 AsAppIdKind
 as_app_id_kind_from_string (const gchar *id_kind)
@@ -187,6 +201,13 @@ as_app_id_kind_from_string (const gchar *id_kind)
 
 /**
  * as_app_icon_kind_to_string:
+ * @icon_kind: the @AsAppIconKind.
+ *
+ * Converts the enumerated value to an text representation.
+ *
+ * Returns: string version of @icon_kind
+ *
+ * Since: 0.1.0
  **/
 const gchar *
 as_app_icon_kind_to_string (AsAppIconKind icon_kind)
@@ -202,6 +223,13 @@ as_app_icon_kind_to_string (AsAppIconKind icon_kind)
 
 /**
  * as_app_icon_kind_from_string:
+ * @icon_kind: the string.
+ *
+ * Converts the text representation to an enumerated value.
+ *
+ * Returns: a #AsAppIconKind or %AS_APP_ICON_KIND_UNKNOWN for unknown
+ *
+ * Since: 0.1.0
  **/
 AsAppIconKind
 as_app_icon_kind_from_string (const gchar *icon_kind)
@@ -217,9 +245,15 @@ as_app_icon_kind_from_string (const gchar *icon_kind)
 
 /******************************************************************************/
 
-
 /**
  * as_app_get_id_full:
+ * @app: a #AsApp instance.
+ *
+ * Gets the full ID value.
+ *
+ * Returns: the ID, e.g. "org.gnome.Software.desktop"
+ *
+ * Since: 0.1.0
  **/
 const gchar *
 as_app_get_id_full (AsApp *app)
@@ -230,6 +264,13 @@ as_app_get_id_full (AsApp *app)
 
 /**
  * as_app_get_id:
+ * @app: a #AsApp instance.
+ *
+ * Returns the short version of the ID.
+ *
+ * Returns: the short ID, e.g. "org.gnome.Software"
+ *
+ * Since: 0.1.0
  **/
 const gchar *
 as_app_get_id (AsApp *app)
@@ -240,6 +281,13 @@ as_app_get_id (AsApp *app)
 
 /**
  * as_app_get_categories:
+ * @app: a #AsApp instance.
+ *
+ * Get the application categories.
+ *
+ * Returns: (element-type utf8) (transfer none): an array
+ *
+ * Since: 0.1.0
  **/
 GPtrArray *
 as_app_get_categories (AsApp *app)
@@ -250,6 +298,13 @@ as_app_get_categories (AsApp *app)
 
 /**
  * as_app_get_compulsory_for_desktops:
+ * @app: a #AsApp instance.
+ *
+ * Returns the desktops where this application is compulsory.
+ *
+ * Returns: (element-type utf8) (transfer none): an array
+ *
+ * Since: 0.1.0
  **/
 GPtrArray *
 as_app_get_compulsory_for_desktops (AsApp *app)
@@ -260,6 +315,13 @@ as_app_get_compulsory_for_desktops (AsApp *app)
 
 /**
  * as_app_get_keywords:
+ * @app: a #AsApp instance.
+ *
+ * Gets any keywords the application should match against.
+ *
+ * Returns: (element-type utf8) (transfer none): an array
+ *
+ * Since: 0.1.0
  **/
 GPtrArray *
 as_app_get_keywords (AsApp *app)
@@ -270,6 +332,13 @@ as_app_get_keywords (AsApp *app)
 
 /**
  * as_app_get_releases:
+ * @app: a #AsApp instance.
+ *
+ * Gets all the releases the application has had.
+ *
+ * Returns: (element-type AsRelease) (transfer none): an array
+ *
+ * Since: 0.1.0
  **/
 GPtrArray *
 as_app_get_releases (AsApp *app)
@@ -280,6 +349,13 @@ as_app_get_releases (AsApp *app)
 
 /**
  * as_app_get_screenshots:
+ * @app: a #AsApp instance.
+ *
+ * Gets any screenshots the application has defined.
+ *
+ * Returns: (element-type AsScreenshot) (transfer none): an array
+ *
+ * Since: 0.1.0
  **/
 GPtrArray *
 as_app_get_screenshots (AsApp *app)
@@ -290,7 +366,14 @@ as_app_get_screenshots (AsApp *app)
 
 /**
  * as_app_get_urls:
- */
+ * @app: a #AsApp instance.
+ *
+ * Gets the URLs set for the application.
+ *
+ * Returns: (transfer none): URLs
+ *
+ * Since: 0.1.0
+ **/
 GHashTable *
 as_app_get_urls (AsApp *app)
 {
@@ -300,6 +383,13 @@ as_app_get_urls (AsApp *app)
 
 /**
  * as_app_get_pkgnames:
+ * @app: a #AsApp instance.
+ *
+ * Gets the package names (if any) for the application.
+ *
+ * Returns: (element-type utf8) (transfer none): an array
+ *
+ * Since: 0.1.0
  **/
 GPtrArray *
 as_app_get_pkgnames (AsApp *app)
@@ -310,6 +400,13 @@ as_app_get_pkgnames (AsApp *app)
 
 /**
  * as_app_get_id_kind:
+ * @app: a #AsApp instance.
+ *
+ * Gets the ID kind.
+ *
+ * Returns: enumerated value
+ *
+ * Since: 0.1.0
  **/
 AsAppIdKind
 as_app_get_id_kind (AsApp *app)
@@ -320,6 +417,13 @@ as_app_get_id_kind (AsApp *app)
 
 /**
  * as_app_get_icon_kind:
+ * @app: a #AsApp instance.
+ *
+ * Gets the icon kind.
+ *
+ * Returns: enumerated value
+ *
+ * Since: 0.1.0
  **/
 AsAppIconKind
 as_app_get_icon_kind (AsApp *app)
@@ -330,6 +434,14 @@ as_app_get_icon_kind (AsApp *app)
 
 /**
  * as_app_get_icon:
+ * @app: a #AsApp instance.
+ *
+ * Gets the application icon. Use as_app_get_icon_path() if you need the create
+ * a full filename.
+ *
+ * Returns: string, or %NULL if unset
+ *
+ * Since: 0.1.0
  **/
 const gchar *
 as_app_get_icon (AsApp *app)
@@ -340,6 +452,13 @@ as_app_get_icon (AsApp *app)
 
 /**
  * as_app_get_icon_path:
+ * @app: a #AsApp instance.
+ *
+ * Gets the application icon path.
+ *
+ * Returns: string, or %NULL if unset
+ *
+ * Since: 0.1.0
  **/
 const gchar *
 as_app_get_icon_path (AsApp *app)
@@ -350,6 +469,14 @@ as_app_get_icon_path (AsApp *app)
 
 /**
  * as_app_get_name:
+ * @app: a #AsApp instance.
+ * @locale: the locale, or %NULL. e.g. "en_GB"
+ *
+ * Gets the application name for a specific locale.
+ *
+ * Returns: string, or %NULL if unset
+ *
+ * Since: 0.1.0
  **/
 const gchar *
 as_app_get_name (AsApp *app, const gchar *locale)
@@ -362,6 +489,14 @@ as_app_get_name (AsApp *app, const gchar *locale)
 
 /**
  * as_app_get_comment:
+ * @app: a #AsApp instance.
+ * @locale: the locale, or %NULL. e.g. "en_GB"
+ *
+ * Gets the application summary for a specific locale.
+ *
+ * Returns: string, or %NULL if unset
+ *
+ * Since: 0.1.0
  **/
 const gchar *
 as_app_get_comment (AsApp *app, const gchar *locale)
@@ -374,6 +509,14 @@ as_app_get_comment (AsApp *app, const gchar *locale)
 
 /**
  * as_app_get_description:
+ * @app: a #AsApp instance.
+ * @locale: the locale, or %NULL. e.g. "en_GB"
+ *
+ * Gets the application description markup for a specific locale.
+ *
+ * Returns: string, or %NULL if unset
+ *
+ * Since: 0.1.0
  **/
 const gchar *
 as_app_get_description (AsApp *app, const gchar *locale)
@@ -386,6 +529,14 @@ as_app_get_description (AsApp *app, const gchar *locale)
 
 /**
  * as_app_get_language:
+ * @app: a #AsApp instance.
+ * @locale: the locale, or %NULL. e.g. "en_GB"
+ *
+ * Gets the language coverage for the specific language.
+ *
+ * Returns: a percentage value
+ *
+ * Since: 0.1.0
  **/
 gint
 as_app_get_language (AsApp *app, const gchar *locale)
@@ -398,7 +549,14 @@ as_app_get_language (AsApp *app, const gchar *locale)
 
 /**
  * as_app_get_priority:
- */
+ * @app: a #AsApp instance.
+ *
+ * Gets the application priority. Larger values trump smaller values.
+ *
+ * Returns: priority value
+ *
+ * Since: 0.1.0
+ **/
 gint
 as_app_get_priority (AsApp *app)
 {
@@ -408,6 +566,13 @@ as_app_get_priority (AsApp *app)
 
 /**
  * as_app_get_languages:
+ * @app: a #AsApp instance.
+ *
+ * Get a list of all languages.
+ *
+ * Returns: (transfer container) (element-type utf8): list of language values
+ *
+ * Since: 0.1.0
  **/
 GList *
 as_app_get_languages (AsApp *app)
@@ -418,6 +583,14 @@ as_app_get_languages (AsApp *app)
 
 /**
  * as_app_get_url_item:
+ * @app: a #AsApp instance.
+ * @type: the URL type, e.g. "homepage".
+ *
+ * Gets a URL.
+ *
+ * Returns: string, or %NULL if unset
+ *
+ * Since: 0.1.0
  **/
 const gchar *
 as_app_get_url_item (AsApp *app, const gchar *type)
@@ -428,6 +601,14 @@ as_app_get_url_item (AsApp *app, const gchar *type)
 
 /**
  * as_app_get_metadata_item:
+ * @app: a #AsApp instance.
+ * @key: the metadata key.
+ *
+ * Gets some metadata item.
+ *
+ * Returns: string, or %NULL if unset
+ *
+ * Since: 0.1.0
  **/
 const gchar *
 as_app_get_metadata_item (AsApp *app, const gchar *key)
@@ -438,6 +619,13 @@ as_app_get_metadata_item (AsApp *app, const gchar *key)
 
 /**
  * as_app_get_project_group:
+ * @app: a #AsApp instance.
+ *
+ * Gets an application project group.
+ *
+ * Returns: string, or %NULL if unset
+ *
+ * Since: 0.1.0
  **/
 const gchar *
 as_app_get_project_group (AsApp *app)
@@ -448,6 +636,13 @@ as_app_get_project_group (AsApp *app)
 
 /**
  * as_app_get_project_license:
+ * @app: a #AsApp instance.
+ *
+ * Gets the application project license.
+ *
+ * Returns: string, or %NULL if unset
+ *
+ * Since: 0.1.0
  **/
 const gchar *
 as_app_get_project_license (AsApp *app)
@@ -460,6 +655,13 @@ as_app_get_project_license (AsApp *app)
 
 /**
  * as_app_set_id_full:
+ * @app: a #AsApp instance.
+ * @id_full: the new _full_ application ID, e.g. "org.gnome.Software.desktop".
+ * @id_full_len: the size of @id_full, or -1 if %NULL-terminated.
+ *
+ * Sets a new application ID. Any invalid characters will be automatically replaced.
+ *
+ * Since: 0.1.0
  **/
 void
 as_app_set_id_full (AsApp *app, const gchar *id_full, gssize id_full_len)
@@ -477,6 +679,12 @@ as_app_set_id_full (AsApp *app, const gchar *id_full, gssize id_full_len)
 
 /**
  * as_app_set_id_kind:
+ * @app: a #AsApp instance.
+ * @id_kind: the #AsAppIdKind.
+ *
+ * Sets the application kind.
+ *
+ * Since: 0.1.0
  **/
 void
 as_app_set_id_kind (AsApp *app, AsAppIdKind id_kind)
@@ -487,6 +695,13 @@ as_app_set_id_kind (AsApp *app, AsAppIdKind id_kind)
 
 /**
  * as_app_set_project_group:
+ * @app: a #AsApp instance.
+ * @project_group: the project group, e.g. "GNOME".
+ * @project_group_len: the size of @project_group, or -1 if %NULL-terminated.
+ *
+ * Set any project affiliation.
+ *
+ * Since: 0.1.0
  **/
 void
 as_app_set_project_group (AsApp *app,
@@ -500,6 +715,13 @@ as_app_set_project_group (AsApp *app,
 
 /**
  * as_app_set_project_license:
+ * @app: a #AsApp instance.
+ * @project_license: the project license string.
+ * @project_license_len: the size of @project_license, or -1 if %NULL-terminated.
+ *
+ * Set the project license.
+ *
+ * Since: 0.1.0
  **/
 void
 as_app_set_project_license (AsApp *app,
@@ -513,6 +735,13 @@ as_app_set_project_license (AsApp *app,
 
 /**
  * as_app_set_icon:
+ * @app: a #AsApp instance.
+ * @icon: the icon filename or URL.
+ * @icon_len: the size of @icon, or -1 if %NULL-terminated.
+ *
+ * Set the application icon.
+ *
+ * Since: 0.1.0
  **/
 void
 as_app_set_icon (AsApp *app, const gchar *icon, gssize icon_len)
@@ -524,6 +753,13 @@ as_app_set_icon (AsApp *app, const gchar *icon, gssize icon_len)
 
 /**
  * as_app_set_icon_path:
+ * @app: a #AsApp instance.
+ * @icon_path: the local path.
+ * @icon_path_len: the size of @icon_path, or -1 if %NULL-terminated.
+ *
+ * Sets the icon path, where local icons would be found.
+ *
+ * Since: 0.1.0
  **/
 void
 as_app_set_icon_path (AsApp *app, const gchar *icon_path, gssize icon_path_len)
@@ -535,6 +771,12 @@ as_app_set_icon_path (AsApp *app, const gchar *icon_path, gssize icon_path_len)
 
 /**
  * as_app_set_icon_kind:
+ * @app: a #AsApp instance.
+ * @icon_kind: the #AsAppIconKind.
+ *
+ * Sets the icon kind.
+ *
+ * Since: 0.1.0
  **/
 void
 as_app_set_icon_kind (AsApp *app, AsAppIconKind icon_kind)
@@ -545,6 +787,14 @@ as_app_set_icon_kind (AsApp *app, AsAppIconKind icon_kind)
 
 /**
  * as_app_set_name:
+ * @app: a #AsApp instance.
+ * @locale: the locale, or %NULL. e.g. "en_GB"
+ * @name: the application name.
+ * @name_len: the size of @name, or -1 if %NULL-terminated.
+ *
+ * Sets the application name for a specific locale.
+ *
+ * Since: 0.1.0
  **/
 void
 as_app_set_name (AsApp *app,
@@ -562,6 +812,14 @@ as_app_set_name (AsApp *app,
 
 /**
  * as_app_set_comment:
+ * @app: a #AsApp instance.
+ * @locale: the locale, or %NULL. e.g. "en_GB"
+ * @comment: the application summary.
+ * @comment_len: the size of @comment, or -1 if %NULL-terminated.
+ *
+ * Sets the application summary for a specific locale.
+ *
+ * Since: 0.1.0
  **/
 void
 as_app_set_comment (AsApp *app,
@@ -580,6 +838,14 @@ as_app_set_comment (AsApp *app,
 
 /**
  * as_app_set_description:
+ * @app: a #AsApp instance.
+ * @locale: the locale, or %NULL. e.g. "en_GB"
+ * @description: the application description.
+ * @description_len: the size of @description, or -1 if %NULL-terminated.
+ *
+ * Sets the application descrption markup for a specific locale.
+ *
+ * Since: 0.1.0
  **/
 void
 as_app_set_description (AsApp *app,
@@ -598,7 +864,14 @@ as_app_set_description (AsApp *app,
 
 /**
  * as_app_set_priority:
- */
+ * @app: a #AsApp instance.
+ * @priority: the priority.
+ *
+ * Sets the application priority, where 0 is default and positive numbers
+ * are better than negative numbers.
+ *
+ * Since: 0.1.0
+ **/
 void
 as_app_set_priority (AsApp *app, gint priority)
 {
@@ -625,6 +898,13 @@ as_app_array_find_string (GPtrArray *array, const gchar *value)
 
 /**
  * as_app_add_category:
+ * @app: a #AsApp instance.
+ * @category: the category.
+ * @category_len: the size of @category, or -1 if %NULL-terminated.
+ *
+ * Adds a menu category to the application.
+ *
+ * Since: 0.1.0
  **/
 void
 as_app_add_category (AsApp *app, const gchar *category, gssize category_len)
@@ -643,6 +923,13 @@ as_app_add_category (AsApp *app, const gchar *category, gssize category_len)
 
 /**
  * as_app_add_compulsory_for_desktop:
+ * @app: a #AsApp instance.
+ * @compulsory_for_desktop: the desktop string, e.g. "GNOME".
+ * @compulsory_for_desktop_len: the size of @compulsory_for_desktop, or -1 if %NULL-terminated.
+ *
+ * Adds a desktop that requires this application to be installed.
+ *
+ * Since: 0.1.0
  **/
 void
 as_app_add_compulsory_for_desktop (AsApp *app,
@@ -660,6 +947,13 @@ as_app_add_compulsory_for_desktop (AsApp *app,
 
 /**
  * as_app_add_keyword:
+ * @app: a #AsApp instance.
+ * @keyword: the keyword.
+ * @keyword_len: the size of @keyword, or -1 if %NULL-terminated.
+ *
+ * Add a keyword the application should match against.
+ *
+ * Since: 0.1.0
  **/
 void
 as_app_add_keyword (AsApp *app, const gchar *keyword, gssize keyword_len)
@@ -672,6 +966,13 @@ as_app_add_keyword (AsApp *app, const gchar *keyword, gssize keyword_len)
 
 /**
  * as_app_add_mimetype:
+ * @app: a #AsApp instance.
+ * @mimetype: the mimetype.
+ * @mimetype_len: the size of @mimetype, or -1 if %NULL-terminated.
+ *
+ * Adds a mimetype the application can process.
+ *
+ * Since: 0.1.0
  **/
 void
 as_app_add_mimetype (AsApp *app, const gchar *mimetype, gssize mimetype_len)
@@ -684,6 +985,12 @@ as_app_add_mimetype (AsApp *app, const gchar *mimetype, gssize mimetype_len)
 
 /**
  * as_app_add_release:
+ * @app: a #AsApp instance.
+ * @release: a #AsRelease instance.
+ *
+ * Adds a release to an application.
+ *
+ * Since: 0.1.0
  **/
 void
 as_app_add_release (AsApp *app, AsRelease *release)
@@ -694,6 +1001,12 @@ as_app_add_release (AsApp *app, AsRelease *release)
 
 /**
  * as_app_add_screenshot:
+ * @app: a #AsApp instance.
+ * @screenshot: a #AsScreenshot instance.
+ *
+ * Adds a screenshot to an application.
+ *
+ * Since: 0.1.0
  **/
 void
 as_app_add_screenshot (AsApp *app, AsScreenshot *screenshot)
@@ -704,6 +1017,13 @@ as_app_add_screenshot (AsApp *app, AsScreenshot *screenshot)
 
 /**
  * as_app_add_pkgname:
+ * @app: a #AsApp instance.
+ * @pkgname: the package name.
+ * @pkgname_len: the size of @pkgname, or -1 if %NULL-terminated.
+ *
+ * Adds a package name to an application.
+ *
+ * Since: 0.1.0
  **/
 void
 as_app_add_pkgname (AsApp *app, const gchar *pkgname, gssize pkgname_len)
@@ -716,6 +1036,14 @@ as_app_add_pkgname (AsApp *app, const gchar *pkgname, gssize pkgname_len)
 
 /**
  * as_app_add_language:
+ * @app: a #AsApp instance.
+ * @percentage: the percentage completion of the translation.
+ * @locale: the locale, or %NULL. e.g. "en_GB"
+ * @locale_len: the size of @locale, or -1 if %NULL-terminated.
+ *
+ * Adds a language to the application.
+ *
+ * Since: 0.1.0
  **/
 void
 as_app_add_language (AsApp *app,
@@ -733,6 +1061,14 @@ as_app_add_language (AsApp *app,
 
 /**
  * as_app_add_url:
+ * @app: a #AsApp instance.
+ * @type: the URL kind, e.g. "homepage".
+ * @url: the full URL.
+ * @url_len: the size of @url, or -1 if %NULL-terminated.
+ *
+ * Adds some URL data to the application.
+ *
+ * Since: 0.1.0
  **/
 void
 as_app_add_url (AsApp *app, const gchar *type, const gchar *url, gssize url_len)
@@ -745,6 +1081,14 @@ as_app_add_url (AsApp *app, const gchar *type, const gchar *url, gssize url_len)
 
 /**
  * as_app_add_metadata:
+ * @app: a #AsApp instance.
+ * @key: the metadata key.
+ * @value: the value to store.
+ * @value_len: the size of @value, or -1 if %NULL-terminated.
+ *
+ * Adds a metadata entry to the application.
+ *
+ * Since: 0.1.0
  **/
 void
 as_app_add_metadata (AsApp *app,
@@ -763,6 +1107,12 @@ as_app_add_metadata (AsApp *app,
 
 /**
  * as_app_remove_metadata:
+ * @app: a #AsApp instance.
+ * @key: the metadata key.
+ *
+ * Removes a metadata item from the application.
+ *
+ * Since: 0.1.0
  **/
 void
 as_app_remove_metadata (AsApp *app, const gchar *key)
@@ -775,6 +1125,12 @@ as_app_remove_metadata (AsApp *app, const gchar *key)
 
 /**
  * as_app_subsume:
+ * @app: a #AsApp instance.
+ * @donor: the donor.
+ *
+ * Copies information from the donor to the application object.
+ *
+ * Since: 0.1.0
  **/
 void
 as_app_subsume (AsApp *app, AsApp *donor)
@@ -846,7 +1202,15 @@ as_app_node_insert_languages (AsApp *app, GNode *parent)
 }
 
 /**
- * as_app_node_insert:
+ * as_app_node_insert: (skip)
+ * @app: a #AsApp instance.
+ * @parent: the parent #GNode to use..
+ *
+ * Inserts the application into the DOM tree.
+ *
+ * Returns: (transfer full): A populated #GNode
+ *
+ * Since: 0.1.0
  **/
 GNode *
 as_app_node_insert (AsApp *app, GNode *parent)
@@ -1179,6 +1543,15 @@ out:
 
 /**
  * as_app_node_parse:
+ * @app: a #AsApp instance.
+ * @node: a #GNode.
+ * @error: A #GError or %NULL.
+ *
+ * Populates the object from a DOM node.
+ *
+ * Returns: %TRUE for success
+ *
+ * Since: 0.1.0
  **/
 gboolean
 as_app_node_parse (AsApp *app, GNode *node, GError **error)
@@ -1201,7 +1574,7 @@ out:
 
 /**
  * as_app_add_tokens:
- */
+ **/
 static void
 as_app_add_tokens (AsApp *app,
 		   const gchar *value,
@@ -1225,7 +1598,7 @@ as_app_add_tokens (AsApp *app,
 
 /**
  * as_app_create_token_cache:
- */
+ **/
 static void
 as_app_create_token_cache (AsApp *app)
 {
@@ -1260,7 +1633,15 @@ as_app_create_token_cache (AsApp *app)
 
 /**
  * as_app_search_matches:
- */
+ * @app: a #AsApp instance.
+ * @search: the search term.
+ *
+ * Searches application data for a specific keyword.
+ *
+ * Returns: a match scrore, where 0 is no match and 100 is the best match.
+ *
+ * Since: 0.1.0
+ **/
 guint
 as_app_search_matches (AsApp *app, const gchar *search)
 {
@@ -1295,6 +1676,12 @@ as_app_search_matches (AsApp *app, const gchar *search)
 
 /**
  * as_app_new:
+ *
+ * Creates a new #AsApp.
+ *
+ * Returns: (transfer full): a #GsApp
+ *
+ * Since: 0.1.0
  **/
 AsApp *
 as_app_new (void)
diff --git a/libappstream-glib/as-app.h b/libappstream-glib/as-app.h
index 39d81ad..521463a 100644
--- a/libappstream-glib/as-app.h
+++ b/libappstream-glib/as-app.h
@@ -23,8 +23,8 @@
 #error "Only <appstream-glib.h> can be included directly."
 #endif
 
-#ifndef AS_APP_H
-#define AS_APP_H
+#ifndef __AS_APP_H
+#define __AS_APP_H
 
 #include <glib-object.h>
 
@@ -58,6 +58,7 @@ typedef enum {
 	AS_APP_ICON_KIND_STOCK,
 	AS_APP_ICON_KIND_CACHED,
 	AS_APP_ICON_KIND_REMOTE,
+	/*< private >*/
 	AS_APP_ICON_KIND_LAST
 } AsAppIconKind;
 
@@ -69,6 +70,7 @@ typedef enum {
 	AS_APP_ID_KIND_INPUT_METHOD,
 	AS_APP_ID_KIND_WEB_APP,
 	AS_APP_ID_KIND_SOURCE,
+	/*< private >*/
 	AS_APP_ID_KIND_LAST
 } AsAppIdKind;
 
@@ -193,4 +195,4 @@ guint		 as_app_search_matches		(AsApp		*app,
 
 G_END_DECLS
 
-#endif /* AS_APP_H */
+#endif /* __AS_APP_H */
diff --git a/libappstream-glib/as-image.c b/libappstream-glib/as-image.c
index 87c9bf3..c247fef 100644
--- a/libappstream-glib/as-image.c
+++ b/libappstream-glib/as-image.c
@@ -73,7 +73,14 @@ as_image_class_init (AsImageClass *klass)
 
 /**
  * as_image_kind_from_string:
- */
+ * @kind: the string.
+ *
+ * Converts the text representation to an enumerated value.
+ *
+ * Returns: (transfer full): a #AsImageKind, or %AS_IMAGE_KIND_UNKNOWN for unknown.
+ *
+ * Since: 0.1.0
+ **/
 AsImageKind
 as_image_kind_from_string (const gchar *kind)
 {
@@ -86,7 +93,14 @@ as_image_kind_from_string (const gchar *kind)
 
 /**
  * as_image_kind_to_string:
- */
+ * @kind: the #AsImageKind.
+ *
+ * Converts the enumerated value to an text representation.
+ *
+ * Returns: string version of @kind
+ *
+ * Since: 0.1.0
+ **/
 const gchar *
 as_image_kind_to_string (AsImageKind kind)
 {
@@ -99,7 +113,14 @@ as_image_kind_to_string (AsImageKind kind)
 
 /**
  * as_image_get_url:
- */
+ * @image: a #AsImage instance.
+ *
+ * Gets the full qualified URL for the image, usually pointing at some mirror.
+ *
+ * Returns: URL
+ *
+ * Since: 0.1.0
+ **/
 const gchar *
 as_image_get_url (AsImage *image)
 {
@@ -109,7 +130,14 @@ as_image_get_url (AsImage *image)
 
 /**
  * as_image_get_width:
- */
+ * @image: a #AsImage instance.
+ *
+ * Gets the image width.
+ *
+ * Returns: width in pixels
+ *
+ * Since: 0.1.0
+ **/
 guint
 as_image_get_width (AsImage *image)
 {
@@ -119,7 +147,14 @@ as_image_get_width (AsImage *image)
 
 /**
  * as_image_get_height:
- */
+ * @image: a #AsImage instance.
+ *
+ * Gets the image height.
+ *
+ * Returns: height in pixels
+ *
+ * Since: 0.1.0
+ **/
 guint
 as_image_get_height (AsImage *image)
 {
@@ -129,7 +164,14 @@ as_image_get_height (AsImage *image)
 
 /**
  * as_image_get_kind:
- */
+ * @image: a #AsImage instance.
+ *
+ * Gets the image kind.
+ *
+ * Returns: the #AsImageKind
+ *
+ * Since: 0.1.0
+ **/
 AsImageKind
 as_image_get_kind (AsImage *image)
 {
@@ -139,7 +181,14 @@ as_image_get_kind (AsImage *image)
 
 /**
  * as_image_set_url:
- */
+ * @image: a #AsImage instance.
+ * @url: the URL.
+ * @url_len: the size of @url, or -1 if %NULL-terminated.
+ *
+ * Sets the fully-qualified mirror URL to use for the image.
+ *
+ * Since: 0.1.0
+ **/
 void
 as_image_set_url (AsImage *image, const gchar *url, gssize url_len)
 {
@@ -150,7 +199,13 @@ as_image_set_url (AsImage *image, const gchar *url, gssize url_len)
 
 /**
  * as_image_set_width:
- */
+ * @image: a #AsImage instance.
+ * @width: the width in pixels.
+ *
+ * Sets the image width.
+ *
+ * Since: 0.1.0
+ **/
 void
 as_image_set_width (AsImage *image, guint width)
 {
@@ -160,7 +215,13 @@ as_image_set_width (AsImage *image, guint width)
 
 /**
  * as_image_set_height:
- */
+ * @image: a #AsImage instance.
+ * @height: the height in pixels.
+ *
+ * Sets the image height.
+ *
+ * Since: 0.1.0
+ **/
 void
 as_image_set_height (AsImage *image, guint height)
 {
@@ -170,7 +231,13 @@ as_image_set_height (AsImage *image, guint height)
 
 /**
  * as_image_set_kind:
- */
+ * @image: a #AsImage instance.
+ * @kind: the #AsImageKind, e.g. %AS_IMAGE_KIND_THUMBNAIL.
+ *
+ * Sets the image kind.
+ *
+ * Since: 0.1.0
+ **/
 void
 as_image_set_kind (AsImage *image, AsImageKind kind)
 {
@@ -179,7 +246,15 @@ as_image_set_kind (AsImage *image, AsImageKind kind)
 }
 
 /**
- * as_image_node_insert:
+ * as_image_node_insert: (skip)
+ * @image: a #AsImage instance.
+ * @parent: the parent #GNode to use..
+ *
+ * Inserts the image into the DOM tree.
+ *
+ * Returns: (transfer full): A populated #GNode
+ *
+ * Since: 0.1.0
  **/
 GNode *
 as_image_node_insert (AsImage *image, GNode *parent)
@@ -209,6 +284,15 @@ as_image_node_insert (AsImage *image, GNode *parent)
 
 /**
  * as_image_node_parse:
+ * @image: a #AsImage instance.
+ * @node: a #GNode.
+ * @error: A #GError or %NULL.
+ *
+ * Populates the object from a DOM node.
+ *
+ * Returns: %TRUE for success
+ *
+ * Since: 0.1.0
  **/
 gboolean
 as_image_node_parse (AsImage *image, GNode *node, GError **error)
@@ -237,6 +321,12 @@ as_image_node_parse (AsImage *image, GNode *node, GError **error)
 
 /**
  * as_image_new:
+ *
+ * Creates a new #AsImage.
+ *
+ * Returns: (transfer full): a #AsImage
+ *
+ * Since: 0.1.0
  **/
 AsImage *
 as_image_new (void)
diff --git a/libappstream-glib/as-image.h b/libappstream-glib/as-image.h
index 7776cd5..ed9355d 100644
--- a/libappstream-glib/as-image.h
+++ b/libappstream-glib/as-image.h
@@ -23,8 +23,8 @@
 #error "Only <appstream-glib.h> can be included directly."
 #endif
 
-#ifndef AS_IMAGE_H
-#define AS_IMAGE_H
+#ifndef __AS_IMAGE_H
+#define __AS_IMAGE_H
 
 #include <glib-object.h>
 
@@ -54,6 +54,7 @@ typedef enum {
 	AS_IMAGE_KIND_UNKNOWN,
 	AS_IMAGE_KIND_SOURCE,
 	AS_IMAGE_KIND_THUMBNAIL,
+	/*< private >*/
 	AS_IMAGE_KIND_LAST
 } AsImageKind;
 
@@ -90,4 +91,4 @@ gboolean	 as_image_node_parse		(AsImage	*image,
 
 G_END_DECLS
 
-#endif /* AS_IMAGE_H */
+#endif /* __AS_IMAGE_H */
diff --git a/libappstream-glib/as-node.c b/libappstream-glib/as-node.c
index b4473d8..683ce18 100644
--- a/libappstream-glib/as-node.c
+++ b/libappstream-glib/as-node.c
@@ -35,7 +35,13 @@ typedef struct
 } AsNodeData;
 
 /**
- * as_node_new:
+ * as_node_new: (skip)
+ *
+ * Creates a new empty tree whicah can have nodes appended to it.
+ *
+ * Returns: (transfer full): a new empty tree
+ *
+ * Since: 0.1.0
  **/
 GNode *
 as_node_new (void)
@@ -62,6 +68,11 @@ as_node_destroy_node_cb (GNode *node, gpointer user_data)
 
 /**
  * as_node_unref:
+ * @node: a #GNode.
+ *
+ * Deallocates all notes in the tree.
+ *
+ * Since: 0.1.0
  **/
 void
 as_node_unref (GNode *node)
@@ -93,7 +104,7 @@ as_node_error_quark (void)
 
 /**
  * as_node_string_replace:
- */
+ **/
 static void
 as_node_string_replace (GString *string, const gchar *search, const gchar *replace)
 {
@@ -270,11 +281,14 @@ as_node_to_xml_string (GString *xml,
 
 /**
  * as_node_to_xml:
- * @dom: a #GNode instance.
+ * @node: a #GNode.
+ * @flags: the AsNodeToXmlFlags, e.g. %AS_NODE_INSERT_FLAG_PRE_ESCAPED.
  *
- * Returns a XML representation of the DOM tree.
+ * Converts a node and it's children to XML.
  *
- * Return value: an allocated string
+ * Returns: (transfer full): a #GString
+ *
+ * Since: 0.1.0
  **/
 GString *
 as_node_to_xml (const GNode *node, AsNodeToXmlFlags flags)
@@ -390,12 +404,16 @@ as_node_text_cb (GMarkupParseContext *context,
 }
 
 /**
- * as_node_from_xml:
+ * as_node_from_xml: (skip)
  * @data: XML data
  * @data_len: Length of @data, or -1 if NULL terminated
  * @error: A #GError or %NULL
  *
- * Parses data into a DOM tree.
+ * Parses XML data into a DOM tree.
+ *
+ * Returns: (transfer full): A populated #GNode tree
+ *
+ * Since: 0.1.0
  **/
 GNode *
 as_node_from_xml (const gchar *data,
@@ -452,12 +470,16 @@ out:
 }
 
 /**
- * as_node_from_file:
+ * as_node_from_file: (skip)
  * @file: file
  * @cancellable: A #GCancellable, or %NULL
  * @error: A #GError or %NULL
  *
- * Parses data into a DOM tree.
+ * Parses an XML file into a DOM tree.
+ *
+ * Returns: (transfer full): A populated #GNode tree
+ *
+ * Since: 0.1.0
  **/
 GNode *
 as_node_from_file (GFile *file, GCancellable *cancellable, GError **error)
@@ -606,6 +628,8 @@ as_node_get_child_node (const GNode *root, const gchar *name)
  * Gets the node name, e.g. "body"
  *
  * Return value: string value
+ *
+ * Since: 0.1.0
  **/
 const gchar *
 as_node_get_name (const GNode *node)
@@ -623,6 +647,8 @@ as_node_get_name (const GNode *node)
  * Gets the node data, e.g. "paragraph text"
  *
  * Return value: string value
+ *
+ * Since: 0.1.0
  **/
 const gchar *
 as_node_get_data (const GNode *node)
@@ -645,6 +671,8 @@ as_node_get_data (const GNode *node)
  * Gets the node data, e.g. "paragraph text"
  *
  * Return value: string value
+ *
+ * Since: 0.1.0
  **/
 gchar *
 as_node_take_data (const GNode *node)
@@ -670,6 +698,8 @@ as_node_take_data (const GNode *node)
  * Gets a node attribute, e.g. 34
  *
  * Return value: integer value
+ *
+ * Since: 0.1.0
  **/
 gint
 as_node_get_attribute_as_int (const GNode *node, const gchar *key)
@@ -699,6 +729,8 @@ out:
  * Gets a node attribute, e.g. "false"
  *
  * Return value: string value
+ *
+ * Since: 0.1.0
  **/
 const gchar *
 as_node_get_attribute (const GNode *node, const gchar *key)
@@ -717,13 +749,15 @@ as_node_get_attribute (const GNode *node, const gchar *key)
 }
 
 /**
- * as_node_find:
+ * as_node_find: (skip)
  * @root: a root node, or %NULL
  * @path: a path in the DOM, e.g. "html/body"
  *
  * Gets a node from the DOM tree.
  *
  * Return value: A #GNode, or %NULL if not found
+ *
+ * Since: 0.1.0
  **/
 GNode *
 as_node_find (GNode *root, const gchar *path)
@@ -746,7 +780,18 @@ out:
 }
 
 /**
- * as_node_insert:
+ * as_node_insert: (skip)
+ * @parent: a parent #GNode.
+ * @name: the tag name, e.g. "id".
+ * @cdata: the tag data, or %NULL, e.g. "org.gnome.Software.desktop".
+ * @insert_flags: any %AsNodeInsertFlags.
+ * @...: any attributes to add to the node, terminated by %NULL
+ *
+ * Inserts a node into the DOM.
+ *
+ * Returns: (transfer full): A populated #GNode
+ *
+ * Since: 0.1.0
  **/
 GNode *
 as_node_insert (GNode *parent,
@@ -799,6 +844,14 @@ as_node_list_sort_cb (gconstpointer a, gconstpointer b)
 
 /**
  * as_node_insert_localized:
+ * @parent: a parent #GNode.
+ * @name: the tag name, e.g. "id".
+ * @localized: the hash table of data, with the locale as the key.
+ * @insert_flags: any %AsNodeInsertFlags.
+ *
+ * Inserts a localized key into the DOM.
+ *
+ * Since: 0.1.0
  **/
 void
 as_node_insert_localized (GNode *parent,
@@ -837,6 +890,15 @@ as_node_insert_localized (GNode *parent,
 
 /**
  * as_node_insert_hash:
+ * @parent: a parent #GNode.
+ * @name: the tag name, e.g. "id".
+ * @attr_key: the key to use as the attribute in the XML, e.g. "key".
+ * @hash: the hash table with the key as the key to use in the XML.
+ * @insert_flags: any %AsNodeInsertFlags.
+ *
+ * Inserts a hash table of data into the DOM.
+ *
+ * Since: 0.1.0
  **/
 void
 as_node_insert_hash (GNode *parent,
@@ -891,6 +953,8 @@ as_node_insert_hash (GNode *parent,
  * Extracts localized values from the DOM tree
  *
  * Return value: (transfer full): A hash table with the locale (e.g. en_GB) as the key
+ *
+ * Since: 0.1.0
  **/
 GHashTable *
 as_node_get_localized (const GNode *node, const gchar *key)
@@ -937,6 +1001,14 @@ out:
 
 /**
  * as_node_get_localized_best:
+ * @node: a #GNode.
+ * @key: the tag name.
+ *
+ * Gets the 'best' locale version of a specific data value.
+ *
+ * Returns: the string value, or %NULL if there was no data
+ *
+ * Since: 0.1.0
  **/
 const gchar *
 as_node_get_localized_best (const GNode *node, const gchar *key)
@@ -975,8 +1047,8 @@ as_node_string_free (GString *string)
  **/
 static void
 as_node_denorm_add_to_langs (GHashTable *hash,
-			    const gchar *data,
-			    gboolean is_start)
+			     const gchar *data,
+			     gboolean is_start)
 {
 	const gchar *xml_lang;
 	GList *keys;
@@ -1023,6 +1095,8 @@ as_node_denorm_get_str_for_lang (GHashTable *hash,
 
 /**
  * as_node_get_localized_unwrap:
+ * @node: a #GNode.
+ * @error: A #GError or %NULL.
  *
  * Denormalize AppData data like this:
  *
@@ -1039,6 +1113,10 @@ as_node_denorm_get_str_for_lang (GHashTable *hash,
  *
  * "C"  ->  "<p>Hi</p><ul><li>First</li></ul>"
  * "pl" ->  "<p>Czesc</p><ul><li>Pierwszy</li></ul>"
+ *
+ * Returns: (transfer full): a hash table of data
+ *
+ * Since: 0.1.0
  **/
 GHashTable *
 as_node_get_localized_unwrap (const GNode *node, GError **error)
diff --git a/libappstream-glib/as-node.h b/libappstream-glib/as-node.h
index 4074820..244fb66 100644
--- a/libappstream-glib/as-node.h
+++ b/libappstream-glib/as-node.h
@@ -37,6 +37,7 @@ typedef enum {
 	AS_NODE_TO_XML_FLAG_ADD_HEADER		= 1,
 	AS_NODE_TO_XML_FLAG_FORMAT_MULTILINE	= 2,
 	AS_NODE_TO_XML_FLAG_FORMAT_INDENT	= 4,
+	/*< private >*/
 	AS_NODE_TO_XML_FLAG_LAST
 } AsNodeToXmlFlags;
 
@@ -44,11 +45,13 @@ typedef enum {
 	AS_NODE_INSERT_FLAG_NONE		= 0,	/* 'bar & baz > foo' */
 	AS_NODE_INSERT_FLAG_PRE_ESCAPED		= 1,	/* 'bar &amp; baz &lt; foo' */
 	AS_NODE_INSERT_FLAG_SWAPPED		= 2,
+	/*< private >*/
 	AS_NODE_INSERT_FLAG_LAST
 } AsNodeInsertFlags;
 
 typedef enum {
 	AS_NODE_ERROR_FAILED,
+	/*< private >*/
 	AS_NODE_ERROR_LAST
 } AsNodeError;
 
diff --git a/libappstream-glib/as-release.c b/libappstream-glib/as-release.c
index 83c226d..f880031 100644
--- a/libappstream-glib/as-release.c
+++ b/libappstream-glib/as-release.c
@@ -74,6 +74,13 @@ as_release_class_init (AsReleaseClass *klass)
 
 /**
  * as_release_get_version:
+ * @release: a #AsRelease instance.
+ *
+ * Gets the release version.
+ *
+ * Returns: string
+ *
+ * Since: 0.1.0
  **/
 const gchar *
 as_release_get_version (AsRelease *release)
@@ -84,6 +91,13 @@ as_release_get_version (AsRelease *release)
 
 /**
  * as_release_get_timestamp:
+ * @release: a #AsRelease instance.
+ *
+ * Gets the release timestamp.
+ *
+ * Returns: timestamp
+ *
+ * Since: 0.1.0
  **/
 guint64
 as_release_get_timestamp (AsRelease *release)
@@ -94,6 +108,13 @@ as_release_get_timestamp (AsRelease *release)
 
 /**
  * as_release_get_description:
+ * @release: a #AsRelease instance.
+ *
+ * Gets the release description markup.
+ *
+ * Returns: markup
+ *
+ * Since: 0.1.0
  **/
 const gchar *
 as_release_get_description (AsRelease *release)
@@ -104,6 +125,13 @@ as_release_get_description (AsRelease *release)
 
 /**
  * as_release_set_version:
+ * @release: a #AsRelease instance.
+ * @version: the version string.
+ * @version_len: the size of @version, or -1 if %NULL-terminated.
+ *
+ * Sets the release version.
+ *
+ * Since: 0.1.0
  **/
 void
 as_release_set_version (AsRelease *release,
@@ -116,6 +144,12 @@ as_release_set_version (AsRelease *release,
 
 /**
  * as_release_set_timestamp:
+ * @release: a #AsRelease instance.
+ * @timestamp: the timestamp value.
+ *
+ * Sets the release timestamp.
+ *
+ * Since: 0.1.0
  **/
 void
 as_release_set_timestamp (AsRelease *release, guint64 timestamp)
@@ -126,6 +160,13 @@ as_release_set_timestamp (AsRelease *release, guint64 timestamp)
 
 /**
  * as_release_set_description:
+ * @release: a #AsRelease instance.
+ * @description: the description markup.
+ * @description_len: the size of @description, or -1 if %NULL-terminated.
+ *
+ * Sets the description release markup.
+ *
+ * Since: 0.1.0
  **/
 void
 as_release_set_description (AsRelease *release,
@@ -137,7 +178,15 @@ as_release_set_description (AsRelease *release,
 }
 
 /**
- * as_release_node_insert:
+ * as_release_node_insert: (skip)
+ * @release: a #AsRelease instance.
+ * @parent: the parent #GNode to use..
+ *
+ * Inserts the release into the DOM tree.
+ *
+ * Returns: (transfer full): A populated #GNode
+ *
+ * Since: 0.1.0
  **/
 GNode *
 as_release_node_insert (AsRelease *release, GNode *parent)
@@ -159,6 +208,15 @@ as_release_node_insert (AsRelease *release, GNode *parent)
 
 /**
  * as_release_node_parse:
+ * @release: a #AsRelease instance.
+ * @node: a #GNode.
+ * @error: A #GError or %NULL.
+ *
+ * Populates the object from a DOM node.
+ *
+ * Returns: %TRUE for success
+ *
+ * Since: 0.1.0
  **/
 gboolean
 as_release_node_parse (AsRelease *release, GNode *node, GError **error)
@@ -178,6 +236,12 @@ as_release_node_parse (AsRelease *release, GNode *node, GError **error)
 
 /**
  * as_release_new:
+ *
+ * Creates a new #AsRelease.
+ *
+ * Returns: (transfer full): a #AsRelease
+ *
+ * Since: 0.1.0
  **/
 AsRelease *
 as_release_new (void)
diff --git a/libappstream-glib/as-release.h b/libappstream-glib/as-release.h
index c744641..a2d79e0 100644
--- a/libappstream-glib/as-release.h
+++ b/libappstream-glib/as-release.h
@@ -23,8 +23,8 @@
 #error "Only <appstream-glib.h> can be included directly."
 #endif
 
-#ifndef AS_RELEASE_H
-#define AS_RELEASE_H
+#ifndef __AS_RELEASE_H
+#define __AS_RELEASE_H
 
 #include <glib-object.h>
 
@@ -77,4 +77,4 @@ gboolean	 as_release_node_parse		(AsRelease	*release,
 
 G_END_DECLS
 
-#endif /* AS_RELEASE_H */
+#endif /* __AS_RELEASE_H */
diff --git a/libappstream-glib/as-screenshot.c b/libappstream-glib/as-screenshot.c
index 4842dc5..857edfe 100644
--- a/libappstream-glib/as-screenshot.c
+++ b/libappstream-glib/as-screenshot.c
@@ -77,7 +77,15 @@ as_screenshot_class_init (AsScreenshotClass *klass)
 
 /**
  * as_screenshot_kind_from_string:
- */
+ * @kind: the string.
+ *
+ * Converts the text representation to an enumerated value.
+ *
+ * Returns: (transfer full): a %AsScreenshotKind, or
+ *                           %AS_SCREENSHOT_KIND_UNKNOWN if not known.
+ *
+ * Since: 0.1.0
+ **/
 AsScreenshotKind
 as_screenshot_kind_from_string (const gchar *kind)
 {
@@ -90,7 +98,14 @@ as_screenshot_kind_from_string (const gchar *kind)
 
 /**
  * as_screenshot_kind_to_string:
- */
+ * @kind: the #AsScreenshotKind.
+ *
+ * Converts the enumerated value to an text representation.
+ *
+ * Returns: string version of @kind
+ *
+ * Since: 0.1.0
+ **/
 const gchar *
 as_screenshot_kind_to_string (AsScreenshotKind kind)
 {
@@ -103,7 +118,14 @@ as_screenshot_kind_to_string (AsScreenshotKind kind)
 
 /**
  * as_screenshot_get_kind:
- */
+ * @screenshot: a #AsScreenshot instance.
+ *
+ * Gets the screenshot kind.
+ *
+ * Returns: a #AsScreenshotKind
+ *
+ * Since: 0.1.0
+ **/
 AsScreenshotKind
 as_screenshot_get_kind (AsScreenshot *screenshot)
 {
@@ -113,7 +135,14 @@ as_screenshot_get_kind (AsScreenshot *screenshot)
 
 /**
  * as_screenshot_get_images:
- */
+ * @screenshot: a #AsScreenshot instance.
+ *
+ * Gets the image sizes included in the screenshot.
+ *
+ * Returns: (element-type AsImage) (transfer none): an array
+ *
+ * Since: 0.1.0
+ **/
 GPtrArray *
 as_screenshot_get_images (AsScreenshot *screenshot)
 {
@@ -123,7 +152,15 @@ as_screenshot_get_images (AsScreenshot *screenshot)
 
 /**
  * as_screenshot_get_caption:
- */
+ * @screenshot: a #AsScreenshot instance.
+ * @locale: the locale, or %NULL. e.g. "en_GB"
+ *
+ * Gets the image caption for a specific locale.
+ *
+ * Returns: the caption
+ *
+ * Since: 0.1.0
+ **/
 const gchar *
 as_screenshot_get_caption (AsScreenshot *screenshot, const gchar *locale)
 {
@@ -135,7 +172,13 @@ as_screenshot_get_caption (AsScreenshot *screenshot, const gchar *locale)
 
 /**
  * as_screenshot_set_kind:
- */
+ * @screenshot: a #AsScreenshot instance.
+ * @kind: the #AsScreenshotKind.
+ *
+ * Sets the screenshot kind.
+ *
+ * Since: 0.1.0
+ **/
 void
 as_screenshot_set_kind (AsScreenshot *screenshot, AsScreenshotKind kind)
 {
@@ -145,7 +188,13 @@ as_screenshot_set_kind (AsScreenshot *screenshot, AsScreenshotKind kind)
 
 /**
  * as_screenshot_add_image:
- */
+ * @screenshot: a #AsScreenshot instance.
+ * @image: a #AsImage instance.
+ *
+ * Adds an image to the screenshot.
+ *
+ * Since: 0.1.0
+ **/
 void
 as_screenshot_add_image (AsScreenshot *screenshot, AsImage *image)
 {
@@ -155,23 +204,39 @@ as_screenshot_add_image (AsScreenshot *screenshot, AsImage *image)
 
 /**
  * as_screenshot_set_caption:
- */
+ * @screenshot: a #AsScreenshot instance.
+ * @locale: the locale, or %NULL. e.g. "en_GB"
+ * @caption: the caption text.
+ * @caption_len: the size of @caption, or -1 if %NULL-terminated.
+ *
+ * Sets a caption on the screenshot for a specific locale.
+ *
+ * Since: 0.1.0
+ **/
 void
 as_screenshot_set_caption (AsScreenshot *screenshot,
 			   const gchar *locale,
 			   const gchar *caption,
-			   gsize caption_length)
+			   gsize caption_len)
 {
 	AsScreenshotPrivate *priv = GET_PRIVATE (screenshot);
 	if (locale == NULL)
 		locale = "C";
 	g_hash_table_insert (priv->captions,
 			     g_strdup (locale),
-			     as_strndup (caption, caption_length));
+			     as_strndup (caption, caption_len));
 }
 
 /**
- * as_screenshot_node_insert:
+ * as_screenshot_node_insert: (skip)
+ * @screenshot: a #AsScreenshot instance.
+ * @parent: the parent #GNode to use..
+ *
+ * Inserts the screenshot into the DOM tree.
+ *
+ * Returns: (transfer full): A populated #GNode
+ *
+ * Since: 0.1.0
  **/
 GNode *
 as_screenshot_node_insert (AsScreenshot *screenshot, GNode *parent)
@@ -195,6 +260,15 @@ as_screenshot_node_insert (AsScreenshot *screenshot, GNode *parent)
 
 /**
  * as_screenshot_node_parse:
+ * @screenshot: a #AsScreenshot instance.
+ * @node: a #GNode.
+ * @error: A #GError or %NULL.
+ *
+ * Populates the object from a DOM node.
+ *
+ * Returns: %TRUE for success
+ *
+ * Since: 0.1.0
  **/
 gboolean
 as_screenshot_node_parse (AsScreenshot *screenshot, GNode *node, GError **error)
@@ -248,6 +322,12 @@ out:
 
 /**
  * as_screenshot_new:
+ *
+ * Creates a new #AsScreenshot.
+ *
+ * Returns: (transfer full): a #AsScreenshot
+ *
+ * Since: 0.1.0
  **/
 AsScreenshot *
 as_screenshot_new (void)
diff --git a/libappstream-glib/as-screenshot.h b/libappstream-glib/as-screenshot.h
index c820d01..e439eb2 100644
--- a/libappstream-glib/as-screenshot.h
+++ b/libappstream-glib/as-screenshot.h
@@ -23,8 +23,8 @@
 #error "Only <appstream-glib.h> can be included directly."
 #endif
 
-#ifndef AS_SCREENSHOT_H
-#define AS_SCREENSHOT_H
+#ifndef __AS_SCREENSHOT_H
+#define __AS_SCREENSHOT_H
 
 #include <glib-object.h>
 
@@ -53,9 +53,10 @@ struct _AsScreenshotClass
 };
 
 typedef enum {
+	AS_SCREENSHOT_KIND_UNKNOWN,
 	AS_SCREENSHOT_KIND_NORMAL,
 	AS_SCREENSHOT_KIND_DEFAULT,
-	AS_SCREENSHOT_KIND_UNKNOWN,
+	/*< private >*/
 	AS_SCREENSHOT_KIND_LAST
 } AsScreenshotKind;
 
@@ -78,7 +79,7 @@ void		 as_screenshot_set_kind		(AsScreenshot	*screenshot,
 void		 as_screenshot_set_caption	(AsScreenshot	*screenshot,
 						 const gchar	*locale,
 						 const gchar	*caption,
-						 gsize		 caption_length);
+						 gsize		 caption_len);
 void		 as_screenshot_add_image	(AsScreenshot	*screenshot,
 						 AsImage	*image);
 
@@ -91,4 +92,4 @@ gboolean	 as_screenshot_node_parse	(AsScreenshot	*screenshot,
 
 G_END_DECLS
 
-#endif /* AS_SCREENSHOT_H */
+#endif /* __AS_SCREENSHOT_H */
diff --git a/libappstream-glib/as-store.c b/libappstream-glib/as-store.c
index ebc2700..7e0f58c 100644
--- a/libappstream-glib/as-store.c
+++ b/libappstream-glib/as-store.c
@@ -82,7 +82,15 @@ as_store_class_init (AsStoreClass *klass)
 
 /**
  * as_store_get_size:
- */
+ * @store: a #AsStore instance.
+ *
+ * Gets the size of the store after deduplication and prioritization has
+ * taken place.
+ *
+ * Returns: the number of usable applications in the store
+ *
+ * Since: 0.1.0
+ **/
 guint
 as_store_get_size (AsStore *store)
 {
@@ -93,7 +101,14 @@ as_store_get_size (AsStore *store)
 
 /**
  * as_store_get_apps:
- */
+ * @store: a #AsStore instance.
+ *
+ * Gets an array of all the valid applications in the store.
+ *
+ * Returns: (element-type AsApp) (transfer none): an array
+ *
+ * Since: 0.1.0
+ **/
 GPtrArray *
 as_store_get_apps (AsStore *store)
 {
@@ -104,7 +119,15 @@ as_store_get_apps (AsStore *store)
 
 /**
  * as_store_get_app_by_id:
- */
+ * @store: a #AsStore instance.
+ * @id: the application short ID.
+ *
+ * Finds an application in the store by ID.
+ *
+ * Returns: (transfer none): a #GsApp or %NULL
+ *
+ * Since: 0.1.0
+ **/
 AsApp *
 as_store_get_app_by_id (AsStore *store, const gchar *id)
 {
@@ -115,7 +138,15 @@ as_store_get_app_by_id (AsStore *store, const gchar *id)
 
 /**
  * as_store_get_app_by_pkgname:
- */
+ * @store: a #AsStore instance.
+ * @pkgname: the package name.
+ *
+ * Finds an application in the store by package name.
+ *
+ * Returns: (transfer none): a #GsApp or %NULL
+ *
+ * Since: 0.1.0
+ **/
 AsApp *
 as_store_get_app_by_pkgname (AsStore *store, const gchar *pkgname)
 {
@@ -126,7 +157,7 @@ as_store_get_app_by_pkgname (AsStore *store, const gchar *pkgname)
 
 /**
  * as_store_add_app:
- */
+ **/
 static void
 as_store_add_app (AsStore *store, AsApp *app)
 {
@@ -182,7 +213,18 @@ as_store_add_app (AsStore *store, AsApp *app)
 
 /**
  * as_store_parse_file:
- */
+ * @store: a #AsStore instance.
+ * @file: a #GFile.
+ * @path_icons: the icon path for the applications, or %NULL.
+ * @cancellable: a #GCancellable.
+ * @error: A #GError or %NULL.
+ *
+ * Parses an AppStream XML file and adds any valid applications to the store.
+ *
+ * Returns: %TRUE for success
+ *
+ * Since: 0.1.0
+ **/
 gboolean
 as_store_parse_file (AsStore *store,
 		     GFile *file,
@@ -206,7 +248,8 @@ as_store_parse_file (AsStore *store,
 	apps = as_node_find (root, "applications");
 	for (n = apps->children; n != NULL; n = n->next) {
 		app = as_app_new ();
-		as_app_set_icon_path (app, path_icons, -1);
+		if (path_icons != NULL)
+			as_app_set_icon_path (app, path_icons, -1);
 		ret = as_app_node_parse (app, n, error);
 		if (!ret) {
 			g_object_unref (app);
@@ -222,6 +265,12 @@ out:
 
 /**
  * as_store_new:
+ *
+ * Creates a new #AsStore.
+ *
+ * Returns: (transfer full): a #AsStore
+ *
+ * Since: 0.1.0
  **/
 AsStore *
 as_store_new (void)
diff --git a/libappstream-glib/as-store.h b/libappstream-glib/as-store.h
index 0213d3d..f6618ea 100644
--- a/libappstream-glib/as-store.h
+++ b/libappstream-glib/as-store.h
@@ -23,8 +23,8 @@
 #error "Only <appstream-glib.h> can be included directly."
 #endif
 
-#ifndef AS_STORE_H
-#define AS_STORE_H
+#ifndef __AS_STORE_H
+#define __AS_STORE_H
 
 #include <glib-object.h>
 #include <gio/gio.h>
@@ -55,7 +55,6 @@ struct _AsStoreClass
 
 GType		 as_store_get_type		(void);
 AsStore		*as_store_new			(void);
-GQuark		 as_store_error_quark		(void);
 
 /* getters */
 guint		 as_store_get_size		(AsStore	*store);
@@ -74,4 +73,4 @@ AsApp		*as_store_get_app_by_pkgname	(AsStore	*store,
 
 G_END_DECLS
 
-#endif /* AS_STORE_H */
+#endif /* __AS_STORE_H */
diff --git a/libappstream-glib/as-tag.c b/libappstream-glib/as-tag.c
index 9efa994..a2374e3 100644
--- a/libappstream-glib/as-tag.c
+++ b/libappstream-glib/as-tag.c
@@ -25,7 +25,14 @@
 
 /**
  * as_tag_from_string:
- */
+ * @tag: the string.
+ *
+ * Converts the text representation to an enumerated value.
+ *
+ * Returns: a %AsTag, or %AS_TAG_UNKNOWN if not known.
+ *
+ * Since: 0.1.0
+ **/
 AsTag
 as_tag_from_string (const gchar *tag)
 {
@@ -94,7 +101,14 @@ as_tag_from_string (const gchar *tag)
 
 /**
  * as_tag_to_string:
- */
+ * @tag: the %AsTag value.
+ *
+ * Converts the enumerated value to an text representation.
+ *
+ * Returns: string version of @tag
+ *
+ * Since: 0.1.0
+ **/
 const gchar *
 as_tag_to_string (AsTag tag)
 {
diff --git a/libappstream-glib/as-tag.h b/libappstream-glib/as-tag.h
index f982ea9..37387c6 100644
--- a/libappstream-glib/as-tag.h
+++ b/libappstream-glib/as-tag.h
@@ -23,8 +23,8 @@
 #error "Only <appstream-glib.h> can be included directly."
 #endif
 
-#ifndef AS_TAG_H
-#define AS_TAG_H
+#ifndef __AS_TAG_H
+#define __AS_TAG_H
 
 #include <glib.h>
 
@@ -60,6 +60,7 @@ typedef enum {
 	AS_TAG_VALUE,
 	AS_TAG_RELEASES,
 	AS_TAG_RELEASE,
+	/*< private >*/
 	AS_TAG_LAST
 } AsTag;
 
@@ -68,4 +69,4 @@ const gchar	*as_tag_to_string		(AsTag		 tag);
 
 G_END_DECLS
 
-#endif /* AS_TAG_H */
+#endif /* __AS_TAG_H */
diff --git a/libappstream-glib/as-utils.c b/libappstream-glib/as-utils.c
index b60d235..05bb49e 100644
--- a/libappstream-glib/as-utils.c
+++ b/libappstream-glib/as-utils.c
@@ -25,7 +25,15 @@
 
 /**
  * as_strndup:
- */
+ * @text: the text to copy.
+ * @text_len: the length of @text, or -1 if @text is NULL terminated.
+ *
+ * Copies a string, with an optional length argument.
+ *
+ * Returns: (transfer full): a newly allocated %NULL terminated string
+ *
+ * Since: 0.1.0
+ **/
 gchar *
 as_strndup (const gchar *text, gssize text_len)
 {
diff --git a/libappstream-glib/as-utils.h b/libappstream-glib/as-utils.h
index b70e7cd..4100f3c 100644
--- a/libappstream-glib/as-utils.h
+++ b/libappstream-glib/as-utils.h
@@ -23,8 +23,8 @@
 #error "Only <appstream-glib.h> can be included directly."
 #endif
 
-#ifndef AS_UTILS_H
-#define AS_UTILS_H
+#ifndef __AS_UTILS_H
+#define __AS_UTILS_H
 
 #include <glib.h>
 
@@ -33,4 +33,4 @@ gchar		*as_strndup			(const gchar	*text,
 
 G_END_DECLS
 
-#endif /* AS_UTILS_H */
+#endif /* __AS_UTILS_H */