docs: fix up reference docs a bit

      - require GTK-Doc 1.19
      - remove sgml mode
      - automatically generate gi.types (needs GTK-Doc 1.19)
      - fix https://bugzilla.gnome.org/show_bug.cgi?id=700025
[WIP] - rearange sections a bit
[WIP] - add gi-building, gi-programming sections
[WIP] - mark missing docs with TODO, which is only marginaly
        better than nothing but at least can be grepped :)

https://bugzilla.gnome.org/show_bug.cgi?id=571648

1 files changed, 75 insertions, 30 deletions

diff --git a/girepository/girepository.c b/girepository/girepository.c
index 93c23728..6fc7c77e 100644
--- a/girepository/girepository.c
+++ b/girepository/girepository.c
@@ -34,6 +34,17 @@
 
 #include "config.h"
 
+
+/**
+ * SECTION:girepository
+ * @short_description: GObject Introspection repository manager
+ * @include: girepository.h
+ *
+ * #GIRepository is used to manage repositories of namespaces. Namespaces
+ * are represented on disk by type libraries (.typelib files).
+ */
+
+
 static GIRepository *default_repository = NULL;
 static GSList *search_path = NULL;
 static GSList *override_search_path = NULL;
@@ -146,8 +157,9 @@ init_globals (void)
       char *typelib_dir;
       const gchar *type_lib_path_env;
 
-      /* This variable is intended to take precedence over both the default
-       * search path, as well as anything written into code with g_irepository_prepend_search_path.
+      /* This variable is intended to take precedence over both:
+       *   - the default search path;
+       *   - all g_irepository_prepend_search_path() calls.
        */
       type_lib_path_env = g_getenv ("GI_TYPELIB_PATH");
 
@@ -186,6 +198,14 @@ init_globals (void)
   g_once_init_leave (&initialized, 1);
 }
 
+/**
+ * g_irepository_prepend_search_path:
+ * @directory: (type filename): directory name to prepend to the typelib
+ *   search path
+ *
+ * Prepends @directory to the typelib search path.
+ * See g_irepository_get_search_path().
+ */
 void
 g_irepository_prepend_search_path (const char *directory)
 {
@@ -196,11 +216,11 @@ g_irepository_prepend_search_path (const char *directory)
 /**
  * g_irepository_get_search_path:
  *
- * Returns the search path the GIRepository will use when looking for typelibs.
- * The string is internal to GIRespository and should not be freed, nor should
- * the elements.
+ * Returns the current search path #GIRepository will use when loading
+ * typelib files. The list is internal to #GIRespository and should not
+ * be freed, nor should its string elements.
  *
- * Return value: (element-type filename) (transfer none): list of strings
+ * Returns: (element-type filename) (transfer none): #GSList of strings
  */
 GSList *
 g_irepository_get_search_path (void)
@@ -412,17 +432,19 @@ register_internal (GIRepository *repository,
 
 /**
  * g_irepository_get_dependencies:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @namespace_: Namespace of interest
  *
- * Return an array of all (transitive) dependencies for namespace
- * @namespace_, including version.  The returned strings are of the
- * form <code>namespace-version</code>.
+ * Return an array of all (transitive) versioned dependencies for
+ * @namespace_. Returned strings are of the form
+ * <code>namespace-version</code>.
  *
- * Note: The namespace must have already been loaded using a function
+ * Note: @namespace_ must have already been loaded using a function
  * such as g_irepository_require() before calling this function.
  *
- * Returns: (transfer full): Zero-terminated string array of versioned dependencies
+ * Returns: (transfer full): Zero-terminated string array of versioned
+ *   dependencies
  */
 char **
 g_irepository_get_dependencies (GIRepository *repository,
@@ -440,6 +462,16 @@ g_irepository_get_dependencies (GIRepository *repository,
   return get_typelib_dependencies (typelib);
 }
 
+/**
+ * g_irepository_load_typelib:
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
+ * @typelib: TODO
+ * @flags: TODO
+ * @error: TODO
+ *
+ * TODO
+ */
 const char *
 g_irepository_load_typelib (GIRepository *repository,
 			    GITypelib     *typelib,
@@ -478,7 +510,8 @@ g_irepository_load_typelib (GIRepository *repository,
 
 /**
  * g_irepository_is_registered:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @namespace_: Namespace of interest
  * @version: (allow-none): Required version, may be %NULL for latest
  *
@@ -503,13 +536,13 @@ g_irepository_is_registered (GIRepository *repository,
 /**
  * g_irepository_get_default:
  *
- * Returns the singleton process-global default #GIRepository.  It is
+ * Returns the singleton process-global default #GIRepository. It is
  * not currently supported to have multiple repositories in a
  * particular process, but this function is provided in the unlikely
  * eventuality that it would become possible, and as a convenience for
  * higher level language bindings to conform to the GObject method
  * call conventions.
-
+ *
  * All methods on #GIRepository also accept %NULL as an instance
  * parameter to mean this default repository, which is usually more
  * convenient for C.
@@ -524,7 +557,8 @@ g_irepository_get_default (void)
 
 /**
  * g_irepository_get_n_infos:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @namespace_: Namespace to inspect
  *
  * This function returns the number of metadata entries in
@@ -555,7 +589,8 @@ g_irepository_get_n_infos (GIRepository *repository,
 
 /**
  * g_irepository_get_info:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @namespace_: Namespace to inspect
  * @index: 0-based offset into namespace metadata for entry
  *
@@ -629,7 +664,8 @@ find_by_gtype (GHashTable *table, FindByGTypeData *data, gboolean check_prefix)
 
 /**
  * g_irepository_find_by_gtype:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @gtype: GType to search for
  *
  * Searches all loaded namespaces for a particular #GType.  Note that
@@ -717,7 +753,8 @@ g_irepository_find_by_gtype (GIRepository *repository,
 
 /**
  * g_irepository_find_by_name:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @namespace_: Namespace which will be searched
  * @name: Entry name to find
  *
@@ -776,7 +813,8 @@ find_by_error_domain_foreach (gpointer key,
 
 /**
  * g_irepository_find_by_error_domain:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @domain: a #GError domain
  *
  * Searches for the enum type corresponding to the given #GError
@@ -786,7 +824,6 @@ find_by_error_domain_foreach (gpointer key,
  *
  * Returns: (transfer full): #GIEnumInfo representing metadata about @domain's
  * enum type, or %NULL
- *
  * Since: 1.29.17
  */
 GIEnumInfo *
@@ -839,7 +876,8 @@ collect_namespaces (gpointer key,
 
 /**
  * g_irepository_get_loaded_namespaces:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  *
  * Return the list of currently loaded namespaces.
  *
@@ -868,7 +906,8 @@ g_irepository_get_loaded_namespaces (GIRepository *repository)
 
 /**
  * g_irepository_get_version:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @namespace_: Namespace to inspect
  *
  * This function returns the loaded version associated with the given
@@ -900,7 +939,8 @@ g_irepository_get_version (GIRepository *repository,
 
 /**
  * g_irepository_get_shared_library:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @namespace_: Namespace to inspect
  *
  * This function returns the full path to the shared C library
@@ -937,7 +977,8 @@ g_irepository_get_shared_library (GIRepository *repository,
 
 /**
  * g_irepository_get_c_prefix:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @namespace_: Namespace to inspect
  *
  * This function returns the "C prefix", or the C level namespace
@@ -973,13 +1014,14 @@ g_irepository_get_c_prefix (GIRepository *repository,
 
 /**
  * g_irepository_get_typelib_path:
- * @repository: (allow-none): Repository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @namespace_: GI namespace to use, e.g. "Gtk"
  *
  * If namespace @namespace_ is loaded, return the full path to the
  * .typelib file it was loaded from.  If the typelib for
  * namespace @namespace_ was included in a shared library, return
- * the special string "$lt;builtin$gt;".
+ * the special string "&lt;builtin&gt;".
  *
  * Returns: Filesystem path (or $lt;builtin$gt;) if successful, %NULL if namespace is not loaded
  */
@@ -1248,7 +1290,8 @@ find_namespace_latest (const gchar  *namespace,
 
 /**
  * g_irepository_enumerate_versions:
- * @repository: (allow-none): the repository
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @namespace_: GI namespace, e.g. "Gtk"
  *
  * Obtain an unordered list of versions (either currently loaded or
@@ -1408,7 +1451,8 @@ require_internal (GIRepository  *repository,
 
 /**
  * g_irepository_require:
- * @repository: (allow-none): Repository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @namespace_: GI namespace to use, e.g. "Gtk"
  * @version: (allow-none): Version of namespace, may be %NULL for latest
  * @flags: Set of %GIRepositoryLoadFlags, may be 0
@@ -1442,7 +1486,8 @@ g_irepository_require (GIRepository  *repository,
 
 /**
  * g_irepository_require_private:
- * @repository: (allow-none): Repository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @typelib_dir: Private directory where to find the requested typelib
  * @namespace_: GI namespace to use, e.g. "Gtk"
  * @version: (allow-none): Version of namespace, may be %NULL for latest