Merge pull request #118 from matthiasclasen/library-docs

Some assorted work on the library docs

15 files changed, 424 insertions, 76 deletions

diff --git a/configure.ac b/configure.ac
index 226dfa4..4a06bda 100644
--- a/configure.ac
+++ b/configure.ac
@@ -331,5 +331,6 @@ doc/Makefile
 doc/reference/Makefile
 xdg-app.pc
 lib/xdg-app-version-macros.h
+doc/reference/version.xml
 ])
 AC_OUTPUT
diff --git a/doc/reference/Makefile.am b/doc/reference/Makefile.am
index 8b60508..a7c624a 100644
--- a/doc/reference/Makefile.am
+++ b/doc/reference/Makefile.am
@@ -14,6 +14,7 @@ CFILE_GLOB = $(top_srcdir)/lib/*.c
 IGNORE_HFILES = \
 	xdg-app-enum-types.h \
 	xdg-app-installed-ref-private.h \
+	xdg-app-remote-ref-private.h \
 	xdg-app-remote-private.h
 
 EXTRA_HFILES =
@@ -28,6 +29,8 @@ GTKDOC_LIBS = $(top_builddir)/libxdg-app.la $(BASE_LIBS)
 
 include $(top_srcdir)/gtk-doc.make
 
+EXTRA_DIST += version.xml.in
+
 if ENABLE_GTK_DOC_CHECK
 TESTS_ENVIRONMENT = \
 	DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
diff --git a/doc/reference/version.xml.in b/doc/reference/version.xml.in
new file mode 100644
index 0000000..e1b2fdf
--- /dev/null
+++ b/doc/reference/version.xml.in
@@ -0,0 +1 @@
+@XDG_APP_MAJOR_VERSION@.@XDG_APP_MINOR_VERSION@.@XDG_APP_MICRO_VERSION@
diff --git a/doc/reference/xdg-app-docs.xml b/doc/reference/xdg-app-docs.xml
index 01b0c06..4a1d441 100644
--- a/doc/reference/xdg-app-docs.xml
+++ b/doc/reference/xdg-app-docs.xml
@@ -3,23 +3,24 @@
                "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
 [
   <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+  <!ENTITY version SYSTEM "version.xml">
 ]>
 <book id="index">
   <bookinfo>
-    <title>xdg-app Reference Manual</title>
+    <title>xdg-app Library Reference Manual</title>
     <releaseinfo>
-      for xdg-app 1.0.
+      For xdg-app &version;
     </releaseinfo>
   </bookinfo>
 
   <chapter>
     <title>XDG-App</title>
-    <xi:include href="xml/xdg-app-error.xml"/>
     <xi:include href="xml/xdg-app-installation.xml"/>
+    <xi:include href="xml/xdg-app-ref.xml"/>
     <xi:include href="xml/xdg-app-installed-ref.xml"/>
     <xi:include href="xml/xdg-app-remote-ref.xml"/>
-    <xi:include href="xml/xdg-app-ref.xml"/>
     <xi:include href="xml/xdg-app-remote.xml"/>
+    <xi:include href="xml/xdg-app-error.xml"/>
     <xi:include href="xml/xdg-app-version-macros.xml"/>
   </chapter>
 
@@ -33,10 +34,12 @@
     <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
   </index>
 
+<!-- no deprecated api yet
   <index id="deprecated-api-index" role="deprecated">
     <title>Index of deprecated API</title>
     <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
   </index>
+-->
 
   <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
 </book>
diff --git a/doc/reference/xdg-app-sections.txt b/doc/reference/xdg-app-sections.txt
index b9cfed0..91d3727 100644
--- a/doc/reference/xdg-app-sections.txt
+++ b/doc/reference/xdg-app-sections.txt
@@ -2,74 +2,74 @@
 <FILE>xdg-app-installation</FILE>
 <TITLE>XdgAppInstallation</TITLE>
 XdgAppInstallation
-XdgAppInstallationClass
-xdg_app_installation_create_monitor
-xdg_app_installation_fetch_remote_metadata_sync
-xdg_app_installation_fetch_remote_ref_sync
-xdg_app_installation_fetch_remote_size_sync
-xdg_app_installation_get_current_installed_app
-xdg_app_installation_get_installed_ref
+xdg_app_installation_new_system
+xdg_app_installation_new_user
+xdg_app_installation_new_for_path
 xdg_app_installation_get_is_user
-xdg_app_installation_get_type
+xdg_app_installation_get_path
+xdg_app_installation_create_monitor
 xdg_app_installation_install
+xdg_app_installation_update
+xdg_app_installation_uninstall
 xdg_app_installation_launch
+xdg_app_installation_get_current_installed_app
+xdg_app_installation_get_installed_ref
 xdg_app_installation_list_installed_refs
 xdg_app_installation_list_installed_refs_by_kind
 xdg_app_installation_list_installed_refs_for_update
 xdg_app_installation_list_remote_refs_sync
 xdg_app_installation_list_remotes
+xdg_app_installation_fetch_remote_metadata_sync
+xdg_app_installation_fetch_remote_ref_sync
+xdg_app_installation_fetch_remote_size_sync
 xdg_app_installation_load_app_overrides
-xdg_app_installation_new_for_path
-xdg_app_installation_new_system
-xdg_app_installation_new_user
-xdg_app_installation_uninstall
-xdg_app_installation_update
 xdg_app_installation_update_appstream_sync
+xdg_app_installation_install_bundle
 XdgAppProgressCallback
 XdgAppUpdateFlags
 <SUBSECTION Standard>
 XDG_APP_INSTALLATION
 XDG_APP_IS_INSTALLATION
 XDG_APP_TYPE_INSTALLATION
+XdgAppInstallationClass
+xdg_app_installation_get_type
 </SECTION>
 
 <SECTION>
 <FILE>xdg-app-installed-ref</FILE>
 <TITLE>XdgAppInstalledRef</TITLE>
 XdgAppInstalledRef
-XdgAppInstalledRefClass
 xdg_app_installed_ref_get_deploy_dir
 xdg_app_installed_ref_get_installed_size
 xdg_app_installed_ref_get_is_current
 xdg_app_installed_ref_get_latest_commit
 xdg_app_installed_ref_get_origin
-xdg_app_installed_ref_get_type
 xdg_app_installed_ref_load_metadata
 <SUBSECTION Standard>
+XdgAppInstalledRefClass
 XDG_APP_INSTALLED_REF
 XDG_APP_IS_INSTALLED_REF
 XDG_APP_TYPE_INSTALLED_REF
+xdg_app_installed_ref_get_type
 </SECTION>
 
 <SECTION>
 <FILE>xdg-app-remote-ref</FILE>
 <TITLE>XdgAppRemoteRef</TITLE>
 XdgAppRemoteRef
-XdgAppRemoteRefClass
 xdg_app_remote_ref_get_remote_name
-xdg_app_remote_ref_get_type
-xdg_app_remote_ref_new
 <SUBSECTION Standard>
 XDG_APP_IS_REMOTE_REF
 XDG_APP_REMOTE_REF
 XDG_APP_TYPE_REMOTE_REF
+XdgAppRemoteRefClass
+xdg_app_remote_ref_get_type
 </SECTION>
 
 <SECTION>
 <FILE>xdg-app-ref</FILE>
 <TITLE>XdgAppRef</TITLE>
 XdgAppRef
-XdgAppRefClass
 XdgAppRefKind
 xdg_app_ref_format_ref
 xdg_app_ref_get_arch
@@ -77,19 +77,19 @@ xdg_app_ref_get_branch
 xdg_app_ref_get_commit
 xdg_app_ref_get_kind
 xdg_app_ref_get_name
-xdg_app_ref_get_type
 xdg_app_ref_parse
 <SUBSECTION Standard>
+XdgAppRefClass
 XDG_APP_IS_REF
 XDG_APP_REF
 XDG_APP_TYPE_REF
+xdg_app_ref_get_type
 </SECTION>
 
 <SECTION>
 <FILE>xdg-app-remote</FILE>
 <TITLE>XdgAppRemote</TITLE>
 XdgAppRemote
-XdgAppRemoteClass
 xdg_app_remote_get_appstream_dir
 xdg_app_remote_get_appstream_timestamp
 xdg_app_remote_get_gpg_verify
@@ -97,12 +97,13 @@ xdg_app_remote_get_name
 xdg_app_remote_get_noenumerate
 xdg_app_remote_get_prio
 xdg_app_remote_get_title
-xdg_app_remote_get_type
 xdg_app_remote_get_url
 <SUBSECTION Standard>
+XdgAppRemoteClass
 XDG_APP_IS_REMOTE
 XDG_APP_REMOTE
 XDG_APP_TYPE_REMOTE
+xdg_app_remote_get_type
 </SECTION>
 
 <SECTION>
diff --git a/lib/xdg-app-error.c b/lib/xdg-app-error.c
index f40664a..76984bc 100644
--- a/lib/xdg-app-error.c
+++ b/lib/xdg-app-error.c
@@ -25,4 +25,10 @@
 
 #include <gio/gio.h>
 
+/**
+ * SECTION:xdg-app-error
+ * @Title: Error codes
+ *
+ */
+
 G_DEFINE_QUARK (xdg-app-error-quark, g_io_error)
diff --git a/lib/xdg-app-error.h b/lib/xdg-app-error.h
index b2f371e..4cbda5b 100644
--- a/lib/xdg-app-error.h
+++ b/lib/xdg-app-error.h
@@ -30,6 +30,8 @@ G_BEGIN_DECLS
  * XdgAppError:
  * @XDG_APP_ERROR_ALREADY_INSTALLED: App/runtime is already installed
  * @XDG_APP_ERROR_NOT_INSTALLED: App/runtime is not installed
+ *
+ * Error codes for library functions.
  */
 typedef enum {
   XDG_APP_ERROR_ALREADY_INSTALLED,
diff --git a/lib/xdg-app-installation.c b/lib/xdg-app-installation.c
index 807f631..3ca83b5 100644
--- a/lib/xdg-app-installation.c
+++ b/lib/xdg-app-installation.c
@@ -33,6 +33,23 @@
 #include "xdg-app-run.h"
 #include "xdg-app-error.h"
 
+/**
+ * SECTION:xdg-app-installation
+ * @Title: XdgAppInstallation
+ * @Short_description: Installation information
+ *
+ * XdgAppInstallation is the toplevel object that software installers
+ * should use to operate on an xdg-apps.
+ *
+ * An XdgAppInstallation object provides information about an installation
+ * location for xdg-app applications. Typical installation locations are either
+ * system-wide (in /var/lib/xdg-app) or per-user (in ~/.local/share/xdg-app).
+ *
+ * XdgAppInstallation can list configured remotes as well as installed application
+ * and runtime references (in short: refs). It can also run, install, update and
+ * uninstall applications and runtimes.
+ */
+
 typedef struct _XdgAppInstallationPrivate XdgAppInstallationPrivate;
 
 struct _XdgAppInstallationPrivate
@@ -125,6 +142,15 @@ xdg_app_installation_new_for_dir (XdgAppDir *dir,
   return self;
 }
 
+/**
+ * xdg_app_installation_new_system:
+ * @cancellable: (nullable): a #GCancellable
+ * @error: return location for a #GError
+ *
+ * Creates a new #XdgAppInstallation for the system-wide installation.
+ *
+ * Returns: (transfer full): a new #XdgAppInstallation
+ */
 XdgAppInstallation *
 xdg_app_installation_new_system (GCancellable *cancellable,
                                  GError **error)
@@ -132,6 +158,15 @@ xdg_app_installation_new_system (GCancellable *cancellable,
   return xdg_app_installation_new_for_dir (xdg_app_dir_get_system (), cancellable, error);
 }
 
+/**
+ * xdg_app_installation_new_user:
+ * @cancellable: (nullable): a #GCancellable
+ * @error: return location for a #GError
+ *
+ * Creates a new #XdgAppInstallation for the per-user installation.
+ *
+ * Returns: (transfer full): a new #XdgAppInstallation
+ */
 XdgAppInstallation *
 xdg_app_installation_new_user (GCancellable *cancellable,
                                GError **error)
@@ -139,6 +174,17 @@ xdg_app_installation_new_user (GCancellable *cancellable,
   return xdg_app_installation_new_for_dir (xdg_app_dir_get_user (), cancellable, error);
 }
 
+/**
+ * xdg_app_installation_new_for_path:
+ * @path: a #GFile
+ * @user: whether this is a user-specific location
+ * @cancellable: (nullable): a #GCancellable
+ * @error: return location for a #GError
+ *
+ * Creates a new #XdgAppInstallation for the installation at the given @path.
+ *
+ * Returns: (transfer full): a new #XdgAppInstallation
+ */
 XdgAppInstallation *
 xdg_app_installation_new_for_path (GFile *path, gboolean user,
                                    GCancellable *cancellable,
@@ -147,6 +193,14 @@ xdg_app_installation_new_for_path (GFile *path, gboolean user,
   return xdg_app_installation_new_for_dir (xdg_app_dir_new (path, user), cancellable, error);
 }
 
+/**
+ * xdg_app_installation_get_is_user:
+ * @self: a #XdgAppInstallation
+ *
+ * Returns whether the installation is for a user-specific location.
+ *
+ * Returns: %TRUE if @self is a per-user installation
+ */
 gboolean
 xdg_app_installation_get_is_user (XdgAppInstallation *self)
 {
@@ -156,7 +210,10 @@ xdg_app_installation_get_is_user (XdgAppInstallation *self)
 }
 
 /**
- * xdg_app_installation_get_path
+ * xdg_app_installation_get_path:
+ * @self: a #XdgAppInstallation
+ *
+ * Returns the installation location for @self.
  *
  * Returns: (transfer full): an #GFile
  */
@@ -173,7 +230,7 @@ xdg_app_installation_get_path (XdgAppInstallation *self)
  * @self: a #XdgAppInstallation
  * @name: name of the app to launch
  * @arch: (nullable): which architecture to launch (default: current architecture)
- * @branch: (nullable): which branch of the application (default: 'master')
+ * @branch: (nullable): which branch of the application (default: "master")
  * @commit: (nullable): the commit of @branch to launch
  * @cancellable: (nullable): a #GCancellable
  * @error: return location for a #GError
@@ -184,6 +241,7 @@ xdg_app_installation_get_path (XdgAppInstallation *self)
  * xdg_app_installation_get_current_installed_app() to find out what builds
  * are available, in order to get a value for @commit.
  *
+ * Returns: %TRUE, unless an error occurred
  */
 gboolean
 xdg_app_installation_launch (XdgAppInstallation  *self,
@@ -277,14 +335,14 @@ get_ref (XdgAppInstallation *self,
  * @kind: whether this is an app or runtime
  * @name: name of the app/runtime to fetch
  * @arch: (nullable): which architecture to fetch (default: current architecture)
- * @branch: (nullable): which branch to fetch (default: 'master')
+ * @branch: (nullable): which branch to fetch (default: "master")
  * @cancellable: (nullable): a #GCancellable
  * @error: return location for a #GError
  *
- * Returns information about an installed app or runtime, such as the
- * available builds, its size, location, etc.
+ * Returns information about an installed ref, such as the available builds,
+ * its size, location, etc.
  *
- * Returns: (transfer full): an #XdgAppInstalledRef
+ * Returns: (transfer full): an #XdgAppInstalledRef, or %NULL if an error occurred
  */
 XdgAppInstalledRef *
 xdg_app_installation_get_installed_ref (XdgAppInstallation *self,
@@ -327,9 +385,9 @@ xdg_app_installation_get_installed_ref (XdgAppInstallation *self,
  * @cancellable: (nullable): a #GCancellable
  * @error: return location for a #GError
  *
- * Get the last build of app @name that was installed with
- * xdg_app_installation_install(), or %NULL if the app has never been installed
- * locally.
+ * Get the last build of reference @name that was installed with
+ * xdg_app_installation_install(), or %NULL if the reference has
+ * never been installed locally.
  *
  * Returns: (transfer full): an #XdgAppInstalledRef
  */
@@ -531,7 +589,7 @@ xdg_app_installation_list_installed_refs_for_update (XdgAppInstallation *self,
  * @error: return location for a #GError
  *
  * Lists the remotes, in priority (highest first) order. For same priority,
- * earlier added remote comes before a later added one.
+ * an earlier added remote comes before a later added one.
  *
  * Returns: (transfer container) (element-type XdgAppRemote): an GPtrArray of
  *   #XdgAppRemote instances
@@ -593,6 +651,18 @@ xdg_app_installation_get_remote_by_name (XdgAppInstallation *self,
   return NULL;
 }
 
+/**
+ * xdg_app_installation_load_app_overrides:
+ * @self: a #XdgAppInstallation
+ * @app_id: an application id
+ * @cancellable: (nullable): a #GCancellable
+ * @error: return location for a #GError
+ *
+ * Loads the metadata overrides file for an application.
+ *
+ * Returns: (transfer full): the contents of the overrides files,
+ *    or %NULL if an error occurred
+ */
 char *
 xdg_app_installation_load_app_overrides  (XdgAppInstallation *self,
                                           const char *app_id,
@@ -724,7 +794,8 @@ progress_cb (OstreeAsyncProgress *progress, gpointer user_data)
  * @cancellable: (nullable): a #GCancellable
  * @error: return location for a #GError
  *
- * Install a new ref from a bundle.
+ * Install an application or runtime from an xdg-app bundle file.
+ * See xdg-app-build-bundle(1) for how to create brundles.
  *
  * Returns: (transfer full): The ref for the newly installed app or %NULL on failure
  */
@@ -867,7 +938,7 @@ xdg_app_installation_install_bundle (XdgAppInstallation  *self,
  * @cancellable: (nullable): a #GCancellable
  * @error: return location for a #GError
  *
- * Install a new ref.
+ * Install a new application or runtime.
  *
  * Returns: (transfer full): The ref for the newly installed app or %NULL on failure
  */
@@ -991,7 +1062,7 @@ xdg_app_installation_install (XdgAppInstallation  *self,
  * @cancellable: (nullable): a #GCancellable
  * @error: return location for a #GError
  *
- * Update a ref.
+ * Update an application or runtime.
  *
  * Returns: (transfer full): The ref for the newly updated app (or the same if no update) or %NULL on failure
  */
@@ -1109,7 +1180,7 @@ xdg_app_installation_update (XdgAppInstallation  *self,
  * @cancellable: (nullable): a #GCancellable
  * @error: return location for a #GError
  *
- * Update a ref.
+ * Uninstall an application or runtime.
  *
  * Returns: %TRUE on success
  */
@@ -1205,7 +1276,22 @@ xdg_app_installation_uninstall (XdgAppInstallation  *self,
   return TRUE;
 }
 
-
+/**
+ * xdg_app_installation_fetch_remote_size_sync:
+ * @self: a #XdgAppInstallation
+ * @remote_name: the name of the remote
+ * @commit: the commit
+ * @download_size: (out): return location for the download size
+ * @installed_size: (out): return location for the installed size
+ * @cancellable: (nullable): a #GCancellable
+ * @error: return location for a #GError
+ *
+ * Gets information about the amount of data that needs to be transferred
+ * to pull a commit from a remote repository, and about the amount of
+ * local disk space that is required to check out this commit.
+ *
+ * Returns: %TRUE, unless an error occurred
+ */
 gboolean
 xdg_app_installation_fetch_remote_size_sync (XdgAppInstallation  *self,
                                              const char          *remote_name,
@@ -1226,6 +1312,19 @@ xdg_app_installation_fetch_remote_size_sync (XdgAppInstallation  *self,
                                   error);
 }
 
+/**
+ * xdg_app_installation_fetch_remote_metadata_sync:
+ * @self: a #XdgAppInstallation
+ * @remote_name: the name of the remote
+ * @commit: the commit
+ * @cancellable: (nullable): a #GCancellable
+ * @error: return location for a #GError
+ *
+ * Obtains the metadata file from a commit.
+ *
+ * Returns: (transfer full): a #GBytes containing the xdg-app metadata file,
+ *   or %NULL if an error occurred
+ */
 GBytes *
 xdg_app_installation_fetch_remote_metadata_sync (XdgAppInstallation *self,
                                                  const char *remote_name,
@@ -1255,9 +1354,9 @@ xdg_app_installation_fetch_remote_metadata_sync (XdgAppInstallation *self,
  * @cancellable: (nullable): a #GCancellable
  * @error: return location for a #GError
  *
- * Lists all the refs in a remote.
+ * Lists all the applications and runtimes in a remote.
  *
- * Returns: (transfer container) (element-type XdgAppInstalledRef): an GPtrArray of
+ * Returns: (transfer container) (element-type XdgAppRemoteRef): an GPtrArray of
  *   #XdgAppRemoteRef instances
  */
 GPtrArray *
@@ -1421,7 +1520,9 @@ xdg_app_installation_update_appstream_sync (XdgAppInstallation  *self,
  * @cancellable: (nullable): a #GCancellable
  * @error: return location for a #GError
  *
- * Gets the current remote branch of a ref in the remote.
+ * Gets monitor object for the installation. The returned file monitor will
+ * emit the #GFileMonitor::changed signal whenever an application or runtime
+ * was installed, uninstalled or updated.
  *
  * Returns: (transfer full): a new #GFileMonitor instance, or %NULL on error
  */
diff --git a/lib/xdg-app-installation.h b/lib/xdg-app-installation.h
index 343ecf7..11bb4f4 100644
--- a/lib/xdg-app-installation.h
+++ b/lib/xdg-app-installation.h
@@ -73,6 +73,19 @@ XDG_APP_EXTERN XdgAppInstallation *xdg_app_installation_new_for_path (GFile *pat
                                                                       GCancellable *cancellable,
                                                                       GError **error);
 
+/**
+ * XdgAppProgressCallback:
+ * @status: A status string, suitable for display
+ * @progress: percentage of completion
+ * @estimating: whether @progress is just an estimate
+ * @user_data: User data passed to the caller
+ *
+ * The progress callback is called repeatedly during long-running operations
+ * such as installations or updates, and can be used to update progress information
+ * in a user interface.
+ *
+ * The callback occurs in the thread-default context of the caller.
+ */
 typedef void (*XdgAppProgressCallback)(const char *status,
                                        guint progress,
                                        gboolean estimating,
diff --git a/lib/xdg-app-installed-ref.c b/lib/xdg-app-installed-ref.c
index 4c06810..da29742 100644
--- a/lib/xdg-app-installed-ref.c
+++ b/lib/xdg-app-installed-ref.c
@@ -26,6 +26,16 @@
 #include "xdg-app-installed-ref.h"
 #include "xdg-app-enum-types.h"
 
+/**
+ * SECTION:xdg-app-installed-ref
+ * @Title: XdgAppInstalledRef
+ * @Short_description: Installed application reference
+ *
+ * A XdgAppInstalledRef provides information about an installed
+ * application or runtime (in short: ref), such as the available
+ * builds, its size, location, etc.
+ */
+
 typedef struct _XdgAppInstalledRefPrivate XdgAppInstalledRefPrivate;
 
 struct _XdgAppInstalledRefPrivate
@@ -150,36 +160,36 @@ xdg_app_installed_ref_class_init (XdgAppInstalledRefClass *klass)
   g_object_class_install_property (object_class,
                                    PROP_IS_CURRENT,
                                    g_param_spec_boolean ("is-current",
-                                                         "",
-                                                         "",
+                                                         "Is Current",
+                                                         "Whether the application is current",
                                                          FALSE,
                                                          G_PARAM_READWRITE));
   g_object_class_install_property (object_class,
                                    PROP_INSTALLED_SIZE,
                                    g_param_spec_uint64 ("installed-size",
-                                                         "",
-                                                         "",
+                                                         "Installed Size",
+                                                         "The installed size of the application",
                                                         0, G_MAXUINT64, 0,
                                                          G_PARAM_READWRITE));
   g_object_class_install_property (object_class,
                                    PROP_ORIGIN,
                                    g_param_spec_string ("origin",
-                                                        "",
-                                                        "",
+                                                        "Origin",
+                                                        "The origin",
                                                         NULL,
                                                         G_PARAM_READWRITE));
   g_object_class_install_property (object_class,
                                    PROP_LATEST_COMMIT,
                                    g_param_spec_string ("latest-commit",
-                                                        "",
-                                                        "",
+                                                        "Latest Commit",
+                                                        "The latest commit",
                                                         NULL,
                                                         G_PARAM_READWRITE));
   g_object_class_install_property (object_class,
                                    PROP_DEPLOY_DIR,
                                    g_param_spec_string ("deploy-dir",
-                                                        "",
-                                                        "",
+                                                        "Deploy Dir",
+                                                        "Where the application is installed",
                                                         NULL,
                                                         G_PARAM_READWRITE));
 }
@@ -189,6 +199,14 @@ xdg_app_installed_ref_init (XdgAppInstalledRef *self)
 {
 }
 
+/**
+ * xdg_app_installed_ref_get_origin:
+ * @self: a #XdgAppInstalledRef
+ *
+ * Gets the origin of the ref.
+ *
+ * Returns: (transfer none): the origin
+ */
 const char *
 xdg_app_installed_ref_get_origin (XdgAppInstalledRef *self)
 {
@@ -197,6 +215,14 @@ xdg_app_installed_ref_get_origin (XdgAppInstalledRef *self)
   return priv->origin;
 }
 
+/**
+ * xdg_app_installed_ref_get_latest_commit:
+ * @self: a #XdgAppInstalledRef
+ *
+ * Gets the latest commit of the ref.
+ *
+ * Returns: (transfer none): the latest commit
+ */
 const char *
 xdg_app_installed_ref_get_latest_commit (XdgAppInstalledRef *self)
 {
@@ -205,6 +231,14 @@ xdg_app_installed_ref_get_latest_commit (XdgAppInstalledRef *self)
   return priv->latest_commit;
 }
 
+/**
+ * xdg_app_installed_ref_get_deploy_dir:
+ * @self: a #XdgAppInstalledRef
+ *
+ * Gets the deploy dir of the ref.
+ *
+ * Returns: (transfer none): the deploy dir
+ */
 const char *
 xdg_app_installed_ref_get_deploy_dir (XdgAppInstalledRef *self)
 {
@@ -213,6 +247,14 @@ xdg_app_installed_ref_get_deploy_dir (XdgAppInstalledRef *self)
   return priv->deploy_dir;
 }
 
+/**
+ * xdg_app_installed_ref_get_is_current:
+ * @self: a #XdgAppInstalledRef
+ *
+ * Returns whether the ref is current.
+ *
+ * Returns: %TRUE if the ref is current
+ */
 gboolean
 xdg_app_installed_ref_get_is_current (XdgAppInstalledRef *self)
 {
@@ -221,6 +263,14 @@ xdg_app_installed_ref_get_is_current (XdgAppInstalledRef *self)
   return priv->is_current;
 }
 
+/**
+ * xdg_app_installed_ref_get_installed_size:
+ * @self: a #XdgAppInstalledRef
+ *
+ * Returns the installed size of the ref.
+ *
+ * Returns: the installed size
+ */
 guint64
 xdg_app_installed_ref_get_installed_size (XdgAppInstalledRef *self)
 {
@@ -229,6 +279,17 @@ xdg_app_installed_ref_get_installed_size (XdgAppInstalledRef *self)
   return priv->installed_size;
 }
 
+/**
+ * xdg_app_installed_ref_load_metadata:
+ * @self: a #XdgAppInstalledRef
+ * @cancellable: (nullable): a #GCancellable
+ * @error: a return location for a #GError
+ *
+ * Loads the metadata file for this ref.
+ *
+ * Returns: (transfer full): a #GBytes containing the metadata file,
+ *     or %NULL if an error occurred
+ */
 GBytes *
 xdg_app_installed_ref_load_metadata  (XdgAppInstalledRef *self,
                                       GCancellable *cancellable,
diff --git a/lib/xdg-app-ref.c b/lib/xdg-app-ref.c
index ba48da2..f0c0d76 100644
--- a/lib/xdg-app-ref.c
+++ b/lib/xdg-app-ref.c
@@ -24,6 +24,27 @@
 #include "xdg-app-ref.h"
 #include "xdg-app-enum-types.h"
 
+/**
+ * SECTION:xdg-app-ref
+ * @Title: XdgAppRef
+ * @Short_description: Application reference
+ *
+ * Currently xdg-app manages two types of binary artifacts: applications, and
+ * runtimes. Applications contain a program that desktop users can run, while
+ * runtimes contain only libraries and data. An XdgAppRef object (or short: ref)
+ * can refer to either of these.
+ *
+ * Both applications and runtimes are identified by a 4-tuple of strings: kind,
+ * name, arch and branch, e.g. app/org.gnome.evince/x86_64/master. The functions
+ * xdg_app_ref_parse() and xdg_app_ref_format_ref() can be used to convert
+ * XdgAppRef objects into this string representation and back.
+ *
+ * To uniquely identify a particular version of an application or runtime, you
+ * need a commit.
+ *
+ * The subclasses #XdgAppInstalledRef and #XdgAppRemoteRef provide more information
+ * for artifacts that are locally installed or available from a remote repository.
+ */
 typedef struct _XdgAppRefPrivate XdgAppRefPrivate;
 
 struct _XdgAppRefPrivate
@@ -151,36 +172,36 @@ xdg_app_ref_class_init (XdgAppRefClass *klass)
   g_object_class_install_property (object_class,
                                    PROP_NAME,
                                    g_param_spec_string ("name",
-                                                        "",
-                                                        "",
+                                                        "Name",
+                                                        "The name of the application or runtime",
                                                         NULL,
                                                         G_PARAM_READWRITE));
   g_object_class_install_property (object_class,
                                    PROP_ARCH,
                                    g_param_spec_string ("arch",
-                                                        "",
-                                                        "",
+                                                        "Architecture",
+                                                        "The architecture of the application or runtime",
                                                         NULL,
                                                         G_PARAM_READWRITE));
   g_object_class_install_property (object_class,
                                    PROP_BRANCH,
                                    g_param_spec_string ("branch",
-                                                        "",
-                                                        "",
+                                                        "Branch",
+                                                        "The branch of the application or runtime",
                                                         NULL,
                                                         G_PARAM_READWRITE));
   g_object_class_install_property (object_class,
                                    PROP_COMMIT,
                                    g_param_spec_string ("commit",
-                                                        "",
-                                                        "",
+                                                        "Commit",
+                                                        "The commit",
                                                         NULL,
                                                         G_PARAM_READWRITE));
   g_object_class_install_property (object_class,
                                    PROP_KIND,
                                    g_param_spec_enum ("kind",
-                                                      "",
-                                                      "",
+                                                      "Kind",
+                                                      "The kind of artifact",
                                                       XDG_TYPE_APP_REF_KIND,
                                                       XDG_APP_REF_KIND_APP,
                                                       G_PARAM_READWRITE));
@@ -194,6 +215,14 @@ xdg_app_ref_init (XdgAppRef *self)
   priv->kind = XDG_APP_REF_KIND_APP;
 }
 
+/**
+ * xdg_app_ref_get_name:
+ * @self: a #XdgAppRef
+ *
+ * Gets the name of the ref.
+ *
+ * Returns: (transfer none): the name
+ */
 const char *
 xdg_app_ref_get_name (XdgAppRef *self)
 {
@@ -202,6 +231,14 @@ xdg_app_ref_get_name (XdgAppRef *self)
   return priv->name;
 }
 
+/**
+ * xdg_app_ref_get_arch:
+ * @self: a #XdgAppRef
+ *
+ * Gets the arch or the ref.
+ *
+ * Returns: (transfer none): the arch
+ */
 const char *
 xdg_app_ref_get_arch (XdgAppRef *self)
 {
@@ -210,6 +247,14 @@ xdg_app_ref_get_arch (XdgAppRef *self)
   return priv->arch;
 }
 
+/**
+ * xdg_app_ref_get_branch:
+ * @self: a #XdgAppRef
+ *
+ * Gets the branch of the ref.
+ *
+ * Returns: (transfer none): the branch
+ */
 const char *
 xdg_app_ref_get_branch (XdgAppRef *self)
 {
@@ -218,6 +263,14 @@ xdg_app_ref_get_branch (XdgAppRef *self)
   return priv->branch;
 }
 
+/**
+ * xdg_app_ref_get_commit:
+ * @self: a #XdgAppRef
+ *
+ * Gets the commit of the ref.
+ *
+ * Returns: (transfer none): the commit
+ */
 const char *
 xdg_app_ref_get_commit (XdgAppRef *self)
 {
@@ -226,6 +279,14 @@ xdg_app_ref_get_commit (XdgAppRef *self)
   return priv->commit;
 }
 
+/**
+ * xdg_app_ref_get_kind:
+ * @self: a #XdgAppRef
+ *
+ * Gets the kind of artifact that this ref refers to.
+ *
+ * Returns: the kind of artifact
+ */
 XdgAppRefKind
 xdg_app_ref_get_kind (XdgAppRef *self)
 {
@@ -234,6 +295,15 @@ xdg_app_ref_get_kind (XdgAppRef *self)
   return priv->kind;
 }
 
+/**
+ * xdg_app_ref_format_ref:
+ * @self: a #XdgAppRef
+ *
+ * Convert an XdgAppRef object into a string representation that
+ * can be parsed by xdg_app_ref_parse().
+ *
+ * Returns: (transfer full): string representation
+ */
 char *
 xdg_app_ref_format_ref  (XdgAppRef *self)
 {
@@ -250,7 +320,7 @@ xdg_app_ref_format_ref  (XdgAppRef *self)
 }
 
 /**
- * xdg_app_ref_parse
+ * xdg_app_ref_parse:
  * @ref: A string ref name, such as "app/org.test.App/86_64/master"
  * @error: return location for a #GError
  *
diff --git a/lib/xdg-app-ref.h b/lib/xdg-app-ref.h
index afa4abb..7c060c1 100644
--- a/lib/xdg-app-ref.h
+++ b/lib/xdg-app-ref.h
@@ -53,9 +53,7 @@ G_DEFINE_AUTOPTR_CLEANUP_FUNC(XdgAppRef, g_object_unref)
  * @XDG_APP_REF_KIND_APP: An application
  * @XDG_APP_REF_KIND_RUNTIME: A runtime that applications can use.
  *
- * Currently xdg-app manages two types of binary artifacts: applications, and
- * runtimes. Applications contain a program that desktop users can run, while
- * runtimes contain only libraries and data.
+ * The kind of artifact that a XdgAppRef refers to.
  */
 typedef enum {
   XDG_APP_REF_KIND_APP,
diff --git a/lib/xdg-app-remote-ref.c b/lib/xdg-app-remote-ref.c
index 19eb4b3..6b397db 100644
--- a/lib/xdg-app-remote-ref.c
+++ b/lib/xdg-app-remote-ref.c
@@ -27,6 +27,14 @@
 #include "xdg-app-remote-ref.h"
 #include "xdg-app-enum-types.h"
 
+/**
+ * SECTION:xdg-app-remote-ref
+ * @Title: XdgAppRemoteRef
+ * @Short_description: Remote application reference
+ *
+ * A XdgAppRemoteRef provides information about an application or runtime
+ * (in short: ref) that is available from a remote repository.
+ */
 typedef struct _XdgAppRemoteRefPrivate XdgAppRemoteRefPrivate;
 
 struct _XdgAppRemoteRefPrivate
@@ -108,8 +116,8 @@ xdg_app_remote_ref_class_init (XdgAppRemoteRefClass *klass)
   g_object_class_install_property (object_class,
                                    PROP_REMOTE_NAME,
                                    g_param_spec_string ("remote-name",
-                                                        "",
-                                                        "",
+                                                        "Remote Name",
+                                                        "The name of the remote",
                                                         NULL,
                                                         G_PARAM_READWRITE));
 }
@@ -119,6 +127,14 @@ xdg_app_remote_ref_init (XdgAppRemoteRef *self)
 {
 }
 
+/**
+ * xdg_app_remote_ref_get_remote_name:
+ * @self: a #XdgAppRemoteRef
+ *
+ * Gets the remote name of the ref.
+ *
+ * Returns: (transfer none): the remote name
+ */
 const char *
 xdg_app_remote_ref_get_remote_name (XdgAppRemoteRef *self)
 {
diff --git a/lib/xdg-app-remote.c b/lib/xdg-app-remote.c
index e2d88b8..4a655dc 100644
--- a/lib/xdg-app-remote.c
+++ b/lib/xdg-app-remote.c
@@ -27,6 +27,25 @@
 
 #include <string.h>
 
+/**
+ * SECTION:xdg-app-remote
+ * @Short_description: Remote repository
+ * @Title: XdgAppRemote
+ *
+ * A #XdgAppRemote object provides information about a remote
+ * repository (or short: remote) that has been configured.
+ *
+ * At its most basic level, a remote has a name and the URL for
+ * the repository. In addition, they provide some additional
+ * information that can be useful when presenting repositories
+ * in a UI, such as a title, a priority or a "don't enumerate"
+ * flags.
+ *
+ * To obtain XdgAppRemote objects for the configured remotes
+ * on a system, use xdg_app_installation_list_remotes() or
+ * xdg_app_installation_get_remote_by_name().
+ */
+
 typedef struct _XdgAppRemotePrivate XdgAppRemotePrivate;
 
 struct _XdgAppRemotePrivate
@@ -110,8 +129,8 @@ xdg_app_remote_class_init (XdgAppRemoteClass *klass)
   g_object_class_install_property (object_class,
                                    PROP_NAME,
                                    g_param_spec_string ("name",
-                                                        "",
-                                                        "",
+                                                        "Name",
+                                                        "The name of the remote",
                                                         NULL,
                                                         G_PARAM_READWRITE));
 }
@@ -121,6 +140,14 @@ xdg_app_remote_init (XdgAppRemote *self)
 {
 }
 
+/**
+ * xdg_app_remote_get_name:
+ * @self: a #XdgAppRemote
+ *
+ * Returns the name of the remote repository.
+ *
+ * Returns: (transfer none): the name
+ */
 const char *
 xdg_app_remote_get_name (XdgAppRemote *self)
 {
@@ -130,14 +157,14 @@ xdg_app_remote_get_name (XdgAppRemote *self)
 }
 
 /**
- * xdg_app_remote_get_appstream_dir
+ * xdg_app_remote_get_appstream_dir:
  * @self: a #XdgAppRemote
  * @arch: (nullable): which architecture to fetch (default: current architecture)
  *
  * Returns the directory where this remote will store locally cached
  * appstream information for the specified @arch.
  *
- * Returns: (transfer full): an #GFile
+ * Returns: (transfer full): a #GFile
  **/
 GFile *
 xdg_app_remote_get_appstream_dir (XdgAppRemote *self,
@@ -155,14 +182,14 @@ xdg_app_remote_get_appstream_dir (XdgAppRemote *self,
 }
 
 /**
- * xdg_app_remote_get_appstream_timestamp
+ * xdg_app_remote_get_appstream_timestamp:
  * @self: a #XdgAppRemote
  * @arch: (nullable): which architecture to fetch (default: current architecture)
  *
  * Returns the timestamp file that will be updated whenever the appstream information
  * has been updated (or tried to update) for the specified @arch.
  *
- * Returns: (transfer full): an #GFile
+ * Returns: (transfer full): a #GFile
  **/
 GFile *
 xdg_app_remote_get_appstream_timestamp (XdgAppRemote *self,
@@ -179,6 +206,14 @@ xdg_app_remote_get_appstream_timestamp (XdgAppRemote *self,
                                        subdir);
 }
 
+/**
+ * xdg_app_remote_get_url:
+ * @self: a #XdgAppRemote
+ *
+ * Returns the repository URL of this remote.
+ *
+ * Returns: (transfer full): the URL
+ */
 char *
 xdg_app_remote_get_url (XdgAppRemote *self)
 {
@@ -192,6 +227,14 @@ xdg_app_remote_get_url (XdgAppRemote *self)
   return NULL;
 }
 
+/**
+ * xdg_app_remote_get_title:
+ * @self: a #XdgAppRemote
+ *
+ * Returns the title of the remote.
+ *
+ * Returns: (transfer full): the title
+ */
 char *
 xdg_app_remote_get_title (XdgAppRemote *self)
 {
@@ -200,6 +243,14 @@ xdg_app_remote_get_title (XdgAppRemote *self)
   return xdg_app_dir_get_remote_title (priv->dir, priv->name);
 }
 
+/**
+ * xdg_app_remote_get_noenumerate:
+ * @self: a #XdgAppRemote
+ *
+ * Returns whether this remote should be used to list applications.
+ *
+ * Returns: whether the remote is marked as "don't enumerate"
+ */
 gboolean
 xdg_app_remote_get_noenumerate (XdgAppRemote *self)
 {
@@ -208,6 +259,14 @@ xdg_app_remote_get_noenumerate (XdgAppRemote *self)
   return xdg_app_dir_get_remote_noenumerate (priv->dir, priv->name);
 }
 
+/**
+ * xdg_app_remote_get_prio:
+ * @self: a #XdgAppRemote
+ *
+ * Returns the priority for the remote.
+ *
+ * Returns: the priority
+ */
 int
 xdg_app_remote_get_prio (XdgAppRemote *self)
 {
@@ -216,6 +275,14 @@ xdg_app_remote_get_prio (XdgAppRemote *self)
   return xdg_app_dir_get_remote_prio (priv->dir, priv->name);
 }
 
+/**
+ * xdg_app_remote_get_gpg_verify:
+ * @self: a #XdgAppRemote
+ *
+ * Returns whether GPG verification is enabled for the remote.
+ *
+ * Returns: whether GPG verification is enabled
+ */
 gboolean
 xdg_app_remote_get_gpg_verify (XdgAppRemote *self)
 {
diff --git a/lib/xdg-app-version-macros.h.in b/lib/xdg-app-version-macros.h.in
index 56191b7..e81e25f 100644
--- a/lib/xdg-app-version-macros.h.in
+++ b/lib/xdg-app-version-macros.h.in
@@ -33,4 +33,9 @@
 #define XDG_APP_EXTERN extern
 #endif
 
+/**
+ * SECTION:xdg-app-version-macros
+ * @Title: Version information
+ */
+
 #endif /* __XDG_APP_VERSION_MACROS_H__ */