Commit 5a6df6dd authored by Matthias Clasen's avatar Matthias Clasen

Documentation fixes.

parent 537908e4
2004-10-26 Matthias Clasen <mclasen@redhat.com>
* 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:
......
2004-10-26 Matthias Clasen <mclasen@redhat.com>
* 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:
......
2004-10-26 Matthias Clasen <mclasen@redhat.com>
* 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:
......
2004-10-26 Matthias Clasen <mclasen@redhat.com>
* 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:
......
2004-10-26 Matthias Clasen <mclasen@redhat.com>
* 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:
......
2004-10-26 Matthias Clasen <mclasen@redhat.com>
* 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 <mclasen@redhat.com>
* glib/glib-docs.sgml: Add GKeyFile section, add
......
......@@ -820,6 +820,7 @@ G_BREAKPOINT
<SUBSECTION Private>
g_return_if_fail_warning
g_assert_warning
</SECTION>
<SECTION>
......@@ -959,7 +960,7 @@ GTranslateFunc
g_option_group_set_translate_func
g_option_group_set_translation_domain
<SUBSECTION Private>
g_option_context_error_quark
g_option_error_quark
</SECTION>
......@@ -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
<SUBSECTION>
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
<SUBSECTION>
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
<SUBSECTION Private>
g_key_file_error_quark
</SECTION>
......@@ -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
......
......@@ -316,6 +316,15 @@ error domains.
@Returns:
<!-- ##### FUNCTION g_uri_list_extract_uris ##### -->
<para>
</para>
@uri_list:
@Returns:
<!-- ##### FUNCTION g_locale_from_utf8 ##### -->
<para>
......
<!-- ##### SECTION ./tmpl/desktop_entry.sgml:Long_Description ##### -->
<para>
The "GDesktopEntry" parser is intended to parse files written to
the <ulink
url="http://www.freedesktop.org/Standards/desktop-entry-spec">Desktop
Entry Specification</ulink>. 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.
</para>
<para>
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.
</para>
<para>
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().
</para>
<!-- ##### SECTION ./tmpl/desktop_entry.sgml:See_Also ##### -->
<para>
</para>
<!-- ##### SECTION ./tmpl/desktop_entry.sgml:Short_Description ##### -->
serializes and deserializes a desktop entry.
<!-- ##### SECTION ./tmpl/desktop_entry.sgml:Title ##### -->
Desktop Entry Parser
<!-- ##### ENUM GChannelError ##### -->
<para>
......@@ -51,6 +97,46 @@
@s2:
@Returns:
<!-- ##### STRUCT GDesktopEntry ##### -->
<para>
</para>
<!-- ##### ENUM GDesktopEntryError ##### -->
<para>
Error codes returned by desktop entry parsing.
</para>
@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.
<!-- ##### ENUM GDesktopEntryFlags ##### -->
<para>
#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.
</para>
@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.
<!-- ##### USER_FUNCTION GErrorFunc ##### -->
<para>
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().
</para>
<!-- ##### MACRO G_DESKTOP_ENTRY_ERROR ##### -->
<para>
Error domain for desktop entry parsing. Errors in this domain will
be from the #GDesktopEntryError enumeration. See #GError for information on
error domains.
</para>
<!-- ##### MACRO G_HOOK_DEFERRED_DESTROY ##### -->
<para>
......@@ -211,25 +305,328 @@ in any UNIX manual.
@Returns:
<!-- ##### FUNCTION g_get_language_names ##### -->
<!-- ##### FUNCTION g_desktop_entry_escape_strings ##### -->
<para>
</para>
@entry:
@should_escape:
<!-- ##### FUNCTION g_desktop_entry_free ##### -->
<para>
</para>
@entry:
<!-- ##### FUNCTION g_desktop_entry_get_boolean ##### -->
<para>
</para>
@entry:
@group_name:
@key:
@error:
@Returns:
<!-- ##### FUNCTION g_desktop_entry_get_boolean_list ##### -->
<para>
</para>
@entry:
@group_name:
@key:
@length:
@error:
@Returns:
<!-- ##### FUNCTION g_desktop_entry_get_groups ##### -->
<para>
</para>
@entry:
@length:
@Returns:
<!-- ##### FUNCTION g_desktop_entry_get_integer ##### -->
<para>
</para>
@entry:
@group_name:
@key:
@error:
@Returns:
<!-- ##### FUNCTION g_desktop_entry_get_integer_list ##### -->
<para>
</para>
@entry:
@group_name:
@key:
@length:
@error:
@Returns:
<!-- ##### FUNCTION g_desktop_entry_get_keys ##### -->
<para>
</para>
@entry:
@group_name:
@length:
@error:
@Returns:
<!-- ##### FUNCTION g_desktop_entry_get_locale_string ##### -->
<para>
</para>
@entry:
@group_name:
@key:
@locale:
@error:
@Returns:
<!-- ##### FUNCTION g_desktop_entry_get_locale_string_list ##### -->
<para>
</para>
@entry:
@group_name:
@key:
@locale:
@length:
@error:
@Returns:
<!-- ##### FUNCTION g_desktop_entry_get_start_group ##### -->
<para>
</para>
@entry:
@Returns:
<!-- ##### FUNCTION g_get_system_config_dirs ##### -->
<!-- ##### FUNCTION g_desktop_entry_get_string ##### -->
<para>
</para>
@entry:
@group_name:
@key:
@error:
@Returns:
<!-- ##### FUNCTION g_get_system_data_dirs ##### -->
<!-- ##### FUNCTION g_desktop_entry_get_string_list ##### -->
<para>
</para>
@entry:
@group_name:
@key:
@length:
@error:
@Returns:
<!-- ##### FUNCTION g_desktop_entry_has_group ##### -->
<para>
</para>
@entry:
@group_name:
@Returns:
<!-- ##### FUNCTION g_desktop_entry_has_key ##### -->
<para>
</para>
@entry:
@group_name:
@key:
@error:
@Returns:
<!-- ##### FUNCTION g_desktop_entry_new ##### -->
<para>
</para>
@flags:
@error:
@Returns:
<!-- ##### FUNCTION g_desktop_entry_new_from_data ##### -->
<para>
</para>
@data:
@length:
@legal_start_groups:
@flags:
@error:
@Returns:
<!-- ##### FUNCTION g_desktop_entry_new_from_data_dirs ##### -->
<para>
</para>
@file:
@full_path:
@legal_start_groups:
@flags:
@error:
@Returns:
<!-- ##### FUNCTION g_desktop_entry_new_from_file ##### -->
<para>
</para>
@file:
@legal_start_groups:
@flags:
@error:
@Returns:
<!-- ##### FUNCTION g_desktop_entry_remove_group ##### -->
<para>
</para>
@entry:
@group_name:
@error:
<!-- ##### FUNCTION g_desktop_entry_remove_key ##### -->
<para>
</para>
@entry:
@group_name:
@key:
@error:
<!-- ##### FUNCTION g_desktop_entry_set_boolean ##### -->
<para>
</para>
@entry:
@group_name:
@key:
@boolean:
@error:
<!-- ##### FUNCTION g_desktop_entry_set_boolean_list ##### -->
<para>
</para>
@entry:
@group_name:
@key:
@list:
@length:
@error:
<!-- ##### FUNCTION g_desktop_entry_set_integer ##### -->
<para>
</para>
@entry:
@group_name:
@key:
@integer:
@error:
<!-- ##### FUNCTION g_desktop_entry_set_integer_list ##### -->
<para>
</para>
@entry:
@group_name:
@key:
@list:
@length:
@error:
<!-- ##### FUNCTION g_desktop_entry_set_locale_string ##### -->
<para>
</para>
@entry:
@group_name:
@key:
@locale:
@string:
@error:
<!-- ##### FUNCTION g_desktop_entry_set_locale_string_list ##### -->
<para>
</para>
@entry:
@group_name:
@key:
@locale:
@list:
@length:
@error:
<!-- ##### FUNCTION g_desktop_entry_set_string ##### -->
<para>
</para>
@entry:
@group_name:
@key:
@string:
@error:
<!-- ##### FUNCTION g_desktop_entry_set_string_list ##### -->
<para>
</para>
@entry:
@group_name:
@key:
@list:
@length:
@error:
<!-- ##### FUNCTION g_desktop_entry_to_data ##### -->
<para>
</para>
@entry:
@length:
@error:
@Returns:
<!-- ##### FUNCTION g_io_channel_error_quark ##### -->
......
......@@ -93,3 +93,11 @@ be directly used, e.g. in string array initializers.
@Returns:
<!-- ##### FUNCTION g_get_language_names ##### -->
<para>
</para>
@Returns:
<!-- ##### SECTION Title ##### -->
Key-value file parser
<!-- ##### SECTION Short_Description ##### -->
parses <filename>.ini</filename>-like config files
<!-- ##### SECTION Long_Description ##### -->
<para>
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### STRUCT GKeyFile ##### -->
<para>
The <structname>GKeyFile</structname> struct contains only private fields
and should not be used directly.
</para>
<!-- ##### MACRO G_KEY_FILE_ERROR ##### -->
<para>
Error domain for key file parsing. Errors in this domain will
be from the #GKeyFileError enumeration. See #GError for information on
error domains.
</para>
<!-- ##### ENUM GKeyFileError ##### -->
<para>
Error codes returned by key file parsing.
</para>
@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
<!-- ##### ENUM GKeyFileFlags ##### -->
<para>
Flags which influence the parsing.
</para>
@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.
<!-- ##### FUNCTION g_key_file_new ##### -->
<para>
</para>
@Returns:
<!-- ##### FUNCTION g_key_file_free ##### -->
<para>
</para>
@key_file:
<!-- ##### FUNCTION g_key_file_set_list_separator ##### -->
<para>
</para>
@key_file:
@separator:
<!-- ##### FUNCTION g_key_file_load_from_file ##### -->
<para>
</para>
@key_file:
@file:
@flags:
@error:
@Returns:
<!-- ##### FUNCTION g_key_file_load_from_data ##### -->
<para>
</para>
@key_file:
@data:
@length:
@flags:
@error:
@Returns:
<!-- ##### FUNCTION g_key_file_load_from_data_dirs ##### -->
<para>
</para>
@key_file:
@file:
@full_path:
@flags:
@error:
@Returns:
<!-- ##### FUNCTION g_key_file_to_data ##### -->
<para>
</para>
@key_file:
@length:
@error:
@Returns:
<!-- ##### FUNCTION g_key_file_get_start_group ##### -->
<para>
</para>
@key_file:
@Returns:
<!-- ##### FUNCTION g_key_file_get_groups ##### -->
<para>
</para>
@key_file: