diff options
author | Dieter Verfaillie <dieterv@optionexplicit.be> | 2013-10-10 22:21:18 +0200 |
---|---|---|
committer | Colin Walters <walters@verbum.org> | 2013-10-10 16:48:51 -0400 |
commit | a737daa16e458e87f189c2535f11f4bd2dde8f1a (patch) | |
tree | aeafe6e33e0009a261262219f2286aab248a2ae6 /girepository/girepository.c | |
parent | 3c01854fe58c845956bc8f08e9bd9fd9929b6f8d (diff) | |
download | gobject-introspection-a737daa16e458e87f189c2535f11f4bd2dde8f1a.tar.gz |
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
Diffstat (limited to 'girepository/girepository.c')
-rw-r--r-- | girepository/girepository.c | 105 |
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 "<builtin>". * * 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 |