From 5a6df6dd6552d53dcf6b9d009610988e651ade23 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Tue, 26 Oct 2004 16:10:52 +0000 Subject: [PATCH] Documentation fixes. --- ChangeLog | 5 + ChangeLog.pre-2-10 | 5 + ChangeLog.pre-2-12 | 5 + ChangeLog.pre-2-6 | 5 + ChangeLog.pre-2-8 | 5 + docs/reference/ChangeLog | 15 + docs/reference/glib/glib-sections.txt | 31 +- docs/reference/glib/tmpl/conversions.sgml | 9 + docs/reference/glib/tmpl/glib-unused.sgml | 403 +++++++++++++++++++++++- docs/reference/glib/tmpl/i18n.sgml | 8 + docs/reference/glib/tmpl/keyfile.sgml | 463 ++++++++++++++++++++++++++++ docs/reference/glib/tmpl/macros_misc.sgml | 37 ++- docs/reference/glib/tmpl/main.sgml | 14 +- docs/reference/glib/tmpl/misc_utils.sgml | 16 + docs/reference/gobject/Makefile.am | 3 + docs/reference/gobject/gobject-sections.txt | 9 + glib/gkeyfile.c | 1 - glib/gkeyfile.h | 4 +- 18 files changed, 1001 insertions(+), 37 deletions(-) create mode 100644 docs/reference/glib/tmpl/keyfile.sgml diff --git a/ChangeLog b/ChangeLog index 08771e0..d43723d 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,10 @@ 2004-10-26 Matthias Clasen + * glib/gkeyfile.c (g_key_file_new): Fix docs. + + * glib/gkeyfile.h: Use the same parameter names as in + the implementation and the docs. + * glib/gwin32.c (g_win32_get_windows_version): Make this function thread-safe in the GLib style. * glib/gthreadinit.h: diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index 08771e0..d43723d 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,5 +1,10 @@ 2004-10-26 Matthias Clasen + * glib/gkeyfile.c (g_key_file_new): Fix docs. + + * glib/gkeyfile.h: Use the same parameter names as in + the implementation and the docs. + * glib/gwin32.c (g_win32_get_windows_version): Make this function thread-safe in the GLib style. * glib/gthreadinit.h: diff --git a/ChangeLog.pre-2-12 b/ChangeLog.pre-2-12 index 08771e0..d43723d 100644 --- a/ChangeLog.pre-2-12 +++ b/ChangeLog.pre-2-12 @@ -1,5 +1,10 @@ 2004-10-26 Matthias Clasen + * glib/gkeyfile.c (g_key_file_new): Fix docs. + + * glib/gkeyfile.h: Use the same parameter names as in + the implementation and the docs. + * glib/gwin32.c (g_win32_get_windows_version): Make this function thread-safe in the GLib style. * glib/gthreadinit.h: diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index 08771e0..d43723d 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,5 +1,10 @@ 2004-10-26 Matthias Clasen + * glib/gkeyfile.c (g_key_file_new): Fix docs. + + * glib/gkeyfile.h: Use the same parameter names as in + the implementation and the docs. + * glib/gwin32.c (g_win32_get_windows_version): Make this function thread-safe in the GLib style. * glib/gthreadinit.h: diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index 08771e0..d43723d 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,5 +1,10 @@ 2004-10-26 Matthias Clasen + * glib/gkeyfile.c (g_key_file_new): Fix docs. + + * glib/gkeyfile.h: Use the same parameter names as in + the implementation and the docs. + * glib/gwin32.c (g_win32_get_windows_version): Make this function thread-safe in the GLib style. * glib/gthreadinit.h: diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 62029d5..43a7f1d 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,18 @@ +2004-10-26 Matthias Clasen + + * gobject/gobject-sections.txt: Additions. + + * gobject/Makefile.am (IGNORE_HFILES): Add gobjectalias.h + + * glib/tmpl/main.sgml: Document GChildWatchFunc + + * glib/tmpl/keyfile.sgml: New template. + + * glib/glib-sections.txt: Additions. + + * glib/tmpl/macros_misc.sgml: Document some more of + the macros. + 2004-10-25 Matthias Clasen * glib/glib-docs.sgml: Add GKeyFile section, add diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt index 9450418..4593fa4 100644 --- a/docs/reference/glib/glib-sections.txt +++ b/docs/reference/glib/glib-sections.txt @@ -820,6 +820,7 @@ G_BREAKPOINT g_return_if_fail_warning +g_assert_warning
@@ -959,7 +960,7 @@ GTranslateFunc g_option_group_set_translate_func g_option_group_set_translation_domain -g_option_context_error_quark +g_option_error_quark
@@ -1400,28 +1401,34 @@ g_key_file_get_groups g_key_file_get_keys g_key_file_has_group g_key_file_has_key -g_key_file_remove_group -g_key_file_remove_key g_key_file_get_value -g_key_file_set_value g_key_file_get_string -g_key_file_set_string g_key_file_get_locale_string -g_key_file_set_locale_string g_key_file_get_boolean -g_key_file_set_boolean g_key_file_get_integer -g_key_file_set_integer g_key_file_get_string_list -g_key_file_set_string_list g_key_file_get_locale_string_list -g_key_file_set_locale_string_list g_key_file_get_boolean_list -g_key_file_set_boolean_list g_key_file_get_integer_list +g_key_file_get_comment + + +g_key_file_set_value +g_key_file_set_string +g_key_file_set_locale_string +g_key_file_set_boolean +g_key_file_set_integer +g_key_file_set_string_list +g_key_file_set_locale_string_list +g_key_file_set_boolean_list g_key_file_set_integer_list +g_key_file_set_comment +g_key_file_remove_group +g_key_file_remove_key +g_key_file_remove_comment + g_key_file_error_quark @@ -1470,7 +1477,6 @@ g_completion_free MAXPATHLEN pid_t pipe -ftruncate g_win32_error_message g_win32_getlocale @@ -2060,6 +2066,7 @@ g_filename_to_utf8 g_filename_from_utf8 g_filename_from_uri g_filename_to_uri +g_uri_list_extract_uris g_locale_from_utf8 GConvertError diff --git a/docs/reference/glib/tmpl/conversions.sgml b/docs/reference/glib/tmpl/conversions.sgml index aa14611..b1afdd0 100644 --- a/docs/reference/glib/tmpl/conversions.sgml +++ b/docs/reference/glib/tmpl/conversions.sgml @@ -316,6 +316,15 @@ error domains. @Returns: + + + + + +@uri_list: +@Returns: + + diff --git a/docs/reference/glib/tmpl/glib-unused.sgml b/docs/reference/glib/tmpl/glib-unused.sgml index 9f8cfc0..6cd8c10 100644 --- a/docs/reference/glib/tmpl/glib-unused.sgml +++ b/docs/reference/glib/tmpl/glib-unused.sgml @@ -1,3 +1,49 @@ + + +The "GDesktopEntry" parser is intended to parse files written to +the Desktop +Entry Specification. It supports deserialization of +desktop entries from files and in-memory data. Desktop entries +are used for a variety of things including menus, application +MIME type registration, and launchers. + + + +To load an existing desktop entry from a data directory (as +returned by g_get_user_data_dir() and g_get_system_data_dirs()) +use g_desktop_entry_new_from_data_dirs(). To load an existing +desktop entry from an arbitrary location on the file system use +g_desktop_entry_new_from_file(). If the desktop entry is already +in memory use g_desktop_entry_new_from_data(). Once the desktop +entry is loaded its keys can be queried using the g_desktop_entry_get +family of functions. + + + +To create a new desktop entry first call g_desktop_entry_new(). +Then, call the g_desktop_entry_set family of functions. Next, +call g_desktop_entry_to_data() to output the desktop entry to +a byte array, which can be written to disk or sent over a +network. Finally, call g_desktop_entry_free() to deallocate the +#GDesktopEntry object returned by g_desktop_entry_new(). + + + + + + + + + + +serializes and deserializes a desktop entry. + + + +Desktop Entry Parser + + @@ -51,6 +97,46 @@ @s2: @Returns: + + + + + + + + +Error codes returned by desktop entry parsing. + + +@G_DESKTOP_ENTRY_ERROR_UNKNOWN_ENCODING: text being parsed is not UTF-8 and +cannot be guessed. +@G_DESKTOP_ENTRY_ERROR_BAD_START_GROUP: desktop entry does not start with a +legal start group. +@G_DESKTOP_ENTRY_ERROR_PARSE: desktop entry is empty or contains invalid +data. +@G_DESKTOP_ENTRY_ERROR_NOT_FOUND: valid desktop entry could not be found. +@G_DESKTOP_ENTRY_ERROR_KEY_NOT_FOUND: desktop entry does not have requested +key. +@G_DESKTOP_ENTRY_ERROR_GROUP_NOT_FOUND: desktop entry does not have requested +group +@G_DESKTOP_ENTRY_ERROR_INVALID_VALUE: desktop entry contains key which has +value that cannot be validated. + + + +#GDesktopEntry supports a few flags for tweaking performance during +deserialization. #G_DESKTOP_ENTRY_DISCARD_COMMENTS and +#G_DESKTOP_ENTRY_DISCARD_TRANSLATIONS will reduce memory footprint, +and #G_DESKTOP_ENTRY_GENERATE_LOOKUP_MAP will increase key lookup speed. + + +@G_DESKTOP_ENTRY_NONE: use parser defaults +@G_DESKTOP_ENTRY_DISCARD_COMMENTS: Discard all lines that are blank +or start with "#". +@G_DESKTOP_ENTRY_DISCARD_TRANSLATIONS: Only retain translations that +are returned by g_get_language_names(). +@G_DESKTOP_ENTRY_GENERATE_LOOKUP_MAP: Generate a lookup map for key names to make lookups constant time at the cost of more memory. + Specifies the type of function passed to g_set_error_handler(). @@ -105,6 +191,14 @@ Specifies the type of function passed to g_set_warning_handler(). + + +Error domain for desktop entry parsing. Errors in this domain will +be from the #GDesktopEntryError enumeration. See #GError for information on +error domains. + + + @@ -211,25 +305,328 @@ in any UNIX manual. @Returns: - + + + + + +@entry: +@should_escape: + + + + + + +@entry: + + + + + + +@entry: +@group_name: +@key: +@error: +@Returns: + + + + + + +@entry: +@group_name: +@key: +@length: +@error: +@Returns: + + + + + + +@entry: +@length: +@Returns: + + + + + + +@entry: +@group_name: +@key: +@error: +@Returns: + + + + + + +@entry: +@group_name: +@key: +@length: +@error: +@Returns: + + + + + + +@entry: +@group_name: +@length: +@error: +@Returns: + + + + + + +@entry: +@group_name: +@key: +@locale: +@error: +@Returns: + + + + + + +@entry: +@group_name: +@key: +@locale: +@length: +@error: +@Returns: + + +@entry: @Returns: - + +@entry: +@group_name: +@key: +@error: @Returns: - + + + + + +@entry: +@group_name: +@key: +@length: +@error: +@Returns: + + + + + + +@entry: +@group_name: +@Returns: + + + + + + +@entry: +@group_name: +@key: +@error: +@Returns: + + + + + + +@flags: +@error: +@Returns: + + + + + + +@data: +@length: +@legal_start_groups: +@flags: +@error: +@Returns: + + + + + + +@file: +@full_path: +@legal_start_groups: +@flags: +@error: +@Returns: + + + + + + +@file: +@legal_start_groups: +@flags: +@error: +@Returns: + + + + + + +@entry: +@group_name: +@error: + + + + + + +@entry: +@group_name: +@key: +@error: + + + + + + +@entry: +@group_name: +@key: +@boolean: +@error: + + + + + + +@entry: +@group_name: +@key: +@list: +@length: +@error: + + + + + + +@entry: +@group_name: +@key: +@integer: +@error: + + + + + + +@entry: +@group_name: +@key: +@list: +@length: +@error: + + + + + + +@entry: +@group_name: +@key: +@locale: +@string: +@error: + + + + + + +@entry: +@group_name: +@key: +@locale: +@list: +@length: +@error: + + + + + + +@entry: +@group_name: +@key: +@string: +@error: + + + + + + +@entry: +@group_name: +@key: +@list: +@length: +@error: + + +@entry: +@length: +@error: @Returns: diff --git a/docs/reference/glib/tmpl/i18n.sgml b/docs/reference/glib/tmpl/i18n.sgml index 8e9ac53..fc34eb1 100644 --- a/docs/reference/glib/tmpl/i18n.sgml +++ b/docs/reference/glib/tmpl/i18n.sgml @@ -93,3 +93,11 @@ be directly used, e.g. in string array initializers. @Returns: + + + + + +@Returns: + + diff --git a/docs/reference/glib/tmpl/keyfile.sgml b/docs/reference/glib/tmpl/keyfile.sgml new file mode 100644 index 0000000..f64104c --- /dev/null +++ b/docs/reference/glib/tmpl/keyfile.sgml @@ -0,0 +1,463 @@ + +Key-value file parser + + +parses .ini-like config files + + + + + + + + + + + + + +The GKeyFile struct contains only private fields +and should not be used directly. + + + + + +Error domain for key file parsing. Errors in this domain will +be from the #GKeyFileError enumeration. See #GError for information on +error domains. + + + + + + +Error codes returned by key file parsing. + + +@G_KEY_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was in an unknown encoding +@G_KEY_FILE_ERROR_PARSE: document was ill-formed +@G_KEY_FILE_ERROR_NOT_FOUND: the file was not found +@G_KEY_FILE_ERROR_KEY_NOT_FOUND: a requested key was not found +@G_KEY_FILE_ERROR_GROUP_NOT_FOUND: a requested group was not found +@G_KEY_FILE_ERROR_INVALID_VALUE: a value could not be parsed + + + +Flags which influence the parsing. + + +@G_KEY_FILE_NONE: No flags, default behaviour +@G_KEY_FILE_KEEP_COMMENTS: Use this flag if you plan to write the (possibly modified) + contents of the key file back to a file; otherwise all comments will be lost when + the key file is written back. +@G_KEY_FILE_KEEP_TRANSLATIONS: Use this flag if you plan to write the (possibly modified) + contents of the key file back to a file; otherwise only the translations for the current + language will be written back. + + + + + + +@Returns: + + + + + + + +@key_file: + + + + + + + +@key_file: +@separator: + + + + + + + +@key_file: +@file: +@flags: +@error: +@Returns: + + + + + + + +@key_file: +@data: +@length: +@flags: +@error: +@Returns: + + + + + + + +@key_file: +@file: +@full_path: +@flags: +@error: +@Returns: + + + + + + + +@key_file: +@length: +@error: +@Returns: + + + + + + + +@key_file: +@Returns: + + + + + + + +@key_file: +@length: +@Returns: + + + + + + + +@key_file: +@group_name: +@length: +@error: +@Returns: + + + + + + + +@key_file: +@group_name: +@Returns: + + + + + + + +@key_file: +@group_name: +@key: +@error: +@Returns: + + + + + + + +@key_file: +@group_name: +@key: +@error: +@Returns: + + + + + + + +@key_file: +@group_name: +@key: +@error: +@Returns: + + + + + + + +@key_file: +@group_name: +@key: +@locale: +@error: +@Returns: + + + + + + + +@key_file: +@group_name: +@key: +@error: +@Returns: + + + + + + + +@key_file: +@group_name: +@key: +@error: +@Returns: + + + + + + + +@key_file: +@group_name: +@key: +@length: +@error: +@Returns: + + + + + + + +@key_file: +@group_name: +@key: +@locale: +@length: +@error: +@Returns: + + + + + + + +@key_file: +@group_name: +@key: +@length: +@error: +@Returns: + + + + + + + +@key_file: +@group_name: +@key: +@length: +@error: +@Returns: + + + + + + + +@key_file: +@group_name: +@key: +@error: +@Returns: + + + + + + + +@key_file: +@group_name: +@key: +@value: + + + + + + + +@key_file: +@group_name: +@key: +@string: + + + + + + + +@key_file: +@group_name: +@key: +@locale: +@string: + + + + + + + +@key_file: +@group_name: +@key: +@value: + +@boolean: + + + + + + + +@key_file: +@group_name: +@key: +@value: + +@integer: + + + + + + + +@key_file: +@group_name: +@key: +@list: +@length: + + + + + + + +@key_file: +@group_name: +@key: +@locale: +@list: +@length: + + + + + + + +@key_file: +@group_name: +@key: +@list: +@length: + + + + + + + +@key_file: +@group_name: +@key: +@list: +@length: + + + + + + + +@key_file: +@group_name: +@key: +@comment: +@error: + + + + + + + +@key_file: +@group_name: +@error: + + + + + + + +@key_file: +@group_name: +@key: +@error: + + + + + + + +@key_file: +@group_name: +@key: +@error: + + diff --git a/docs/reference/glib/tmpl/macros_misc.sgml b/docs/reference/glib/tmpl/macros_misc.sgml index 8f631b7..270b258 100644 --- a/docs/reference/glib/tmpl/macros_misc.sgml +++ b/docs/reference/glib/tmpl/macros_misc.sgml @@ -253,18 +253,20 @@ See the GNU C documentation for details. - +This macro is defined as 1 if the the compiler supports ELF visibility +attributes (currently only gcc). +Since: 2.6 Expands to the GNU C visibility(hidden) attribute if the -compiler is gcc. This attribute can be used for marking -library functions as being used internally to the lib only, to not create -inefficient PLT entries. Note that static functions do not need to be marked -as internal in this way. See the GNU C documentation for details. +compiler supports it (currently only gcc). This attribute +can be used for marking library functions as being used internally to the lib +only, to not create inefficient PLT entries. Note that static functions do not +need to be marked as internal in this way. See the GNU C documentation for details. Since: 2.6 @@ -308,17 +310,18 @@ Expands to a string identifying the current code position. - +Expands to a string identifying the current function. +@Since: 2.4 The platform dependent length modifier for constructing printf() conversion -specifiers for values of type #gint16. It is a string literal, but doesn't -include the percent-sign, such that you can add precision and length -modifiers between percent-sign and conversion specifier and append a +specifiers for values of type #gint16 or #guint16. It is a string literal, +but doesn't include the percent-sign, such that you can add precision and +length modifiers between percent-sign and conversion specifier and append a conversion specifier. @@ -368,7 +371,7 @@ printing values of type #guint16. See also #G_GINT16_FORMAT. The platform dependent length modifier for constructing printf() conversion -specifiers for values of type #gint32. See also #G_GINT16_MODIFIER. +specifiers for values of type #gint32 or #guint32. See also #G_GINT16_MODIFIER. @Since: 2.4 @@ -393,7 +396,7 @@ printing values of type #guint32. See also #G_GINT16_FORMAT. The platform dependent length modifier for constructing printf() conversion -specifiers for values of type #gint64. See also #G_GINT16_MODIFIER. +specifiers for values of type #gint64 or #guint64. See also #G_GINT16_MODIFIER. @@ -445,22 +448,28 @@ recommended for parsing anyway; consider using g_strtoull() instead. - +The platform dependent length modifier for constructing printf() conversion +specifiers for values of type #gsize or #gssize. See also #G_GINT16_MODIFIER. +@Since: 2.6 - +This is the platform dependent conversion specifier for scanning and +printing values of type #gsize. See also #G_GINT16_FORMAT. +@Since: 2.6 - +This is the platform dependent conversion specifier for scanning and +printing values of type #gssize. See also #G_GINT16_FORMAT. +@Since: 2.6 diff --git a/docs/reference/glib/tmpl/main.sgml b/docs/reference/glib/tmpl/main.sgml index 731ee1b..ff396f5 100644 --- a/docs/reference/glib/tmpl/main.sgml +++ b/docs/reference/glib/tmpl/main.sgml @@ -595,18 +595,22 @@ for the default main context. - +A type which is used to hold a process identification. +On Unix, processes are identified by a process id (an +integer), while Windows uses process handles (which are +pointers). - +The type of functions to be called when a child exists. -@pid: -@status: -@data: +@pid: the process id of the child process +@status: Status information about the child process, + see waitpid(2) for more information about this field +@data: user data passed to g_child_watch_add() diff --git a/docs/reference/glib/tmpl/misc_utils.sgml b/docs/reference/glib/tmpl/misc_utils.sgml index 1d4e9da..2d66169 100644 --- a/docs/reference/glib/tmpl/misc_utils.sgml +++ b/docs/reference/glib/tmpl/misc_utils.sgml @@ -123,6 +123,22 @@ returned. @Returns: + + + + + +@Returns: + + + + + + + +@Returns: + + Gets the current user's home directory. diff --git a/docs/reference/gobject/Makefile.am b/docs/reference/gobject/Makefile.am index 6e19531..1505594 100644 --- a/docs/reference/gobject/Makefile.am +++ b/docs/reference/gobject/Makefile.am @@ -15,6 +15,9 @@ DOC_SOURCE_DIR=../../../gobject HFILE_GLOB=$(top_srcdir)/gobject/*.h CFILE_GLOB=$(top_srcdir)/gobject/*.c +# Headers to ignore +IGNORE_HFILES=gobjectalias.h + # CFLAGS and LDFLAGS for compiling scan program. Only needed # if $(DOC_MODULE).types is non-empty. INCLUDES = \ diff --git a/docs/reference/gobject/gobject-sections.txt b/docs/reference/gobject/gobject-sections.txt index c8de644d..3101a5a 100644 --- a/docs/reference/gobject/gobject-sections.txt +++ b/docs/reference/gobject/gobject-sections.txt @@ -150,6 +150,15 @@ G_TYPE_RESERVED_USER_FIRST GOBJECT_VAR +g_value_c_init +g_value_types_init +g_enum_types_init +g_param_type_init +g_boxed_type_init +g_object_type_init +g_param_spec_types_init +g_value_transforms_init +g_signal_init
diff --git a/glib/gkeyfile.c b/glib/gkeyfile.c index 1adc21e..4b02af6 100644 --- a/glib/gkeyfile.c +++ b/glib/gkeyfile.c @@ -216,7 +216,6 @@ g_key_file_clear (GKeyFile *key_file) /** * g_key_file_new: - * @flags: flags from #GKeyFileFlags * * Creates a new empty #GKeyFile object. Use g_key_file_load_from_file(), * g_key_file_load_from_data() or g_key_file_load_from_data_dirs() to diff --git a/glib/gkeyfile.h b/glib/gkeyfile.h index b232f7f..8c9f4f7 100644 --- a/glib/gkeyfile.h +++ b/glib/gkeyfile.h @@ -117,7 +117,7 @@ gboolean g_key_file_get_boolean (GKeyFile *key_file, void g_key_file_set_boolean (GKeyFile *key_file, const gchar *group_name, const gchar *key, - gboolean boolean); + gboolean value); gint g_key_file_get_integer (GKeyFile *key_file, const gchar *group_name, const gchar *key, @@ -125,7 +125,7 @@ gint g_key_file_get_integer (GKeyFile *key_file, void g_key_file_set_integer (GKeyFile *key_file, const gchar *group_name, const gchar *key, - gint integer); + gint value); gchar **g_key_file_get_string_list (GKeyFile *key_file, const gchar *group_name, const gchar *key, -- 2.7.4