More doc tweaks

2025-08-22 08:58:54 +02:00 · 2010-04-15 01:47:45 -04:00
parent c850d13330
commit a62300d873
3 changed files with 65 additions and 140 deletions
--- a/docs/reference/gio/#gio-unused.txt#
+++ b/docs/reference/gio/#gio-unused.txt#
@@ -1,100 +0,0 @@
-GFenDirectoryMonitor
-GFenDirectoryMonitorClass
-GFenFileMonitor
-GFenFileMonitorClass
-GLocalFileIOStream
-GLocalFileIOStreamClass
-GLocalFileIOStreamPrivate
-GSocketInputStream
-GSocketInputStreamClass
-GSocketInputStreamPrivate
-GSocketOutputStream
-GSocketOutputStreamClass
-GSocketOutputStreamPrivate
-GWin32DirectoryMonitor
-GWin32DirectoryMonitorClass
-GWin32DirectoryMonitorPrivate
-GWin32Mount
-GWin32MountClass
-GWin32Volume
-GWin32VolumeMonitor
-GWin32VolumeMonitorClass
-GWinHttpDllFuncs
-GWinHttpFile
-GWinHttpFileClass
-GWinHttpFileInputStream
-GWinHttpFileInputStreamClass
-GWinHttpFileOutputStream
-GWinHttpFileOutputStreamClass
-GWinHttpVfs
-GWinHttpVfsClass
-G_FEN_DIRECTORY_MONITOR
-G_FEN_DIRECTORY_MONITOR_CLASS
-G_FEN_FILE_MONITOR
-G_FEN_FILE_MONITOR_CLASS
-G_FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZE
-G_IS_FEN_DIRECTORY_MONITOR
-G_IS_FEN_DIRECTORY_MONITOR_CLASS
-G_IS_FEN_FILE_MONITOR
-G_IS_FEN_FILE_MONITOR_CLASS
-G_IS_LOCAL_FILE_IO_STREAM
-G_IS_LOCAL_FILE_IO_STREAM_CLASS
-G_IS_SOCKET_INPUT_STREAM
-G_IS_SOCKET_INPUT_STREAM_CLASS
-G_IS_SOCKET_OUTPUT_STREAM
-G_IS_SOCKET_OUTPUT_STREAM_CLASS
-G_IS_WIN32_DIRECTORY_MONITOR
-G_IS_WIN32_DIRECTORY_MONITOR_CLASS
-G_IS_WIN32_MOUNT
-G_IS_WIN32_MOUNT_CLASS
-G_IS_WIN32_VOLUME_MONITOR
-G_IS_WIN32_VOLUME_MONITOR_CLASS
-G_IS_WINHTTP_FILE
-G_IS_WINHTTP_FILE_CLASS
-G_IS_WINHTTP_FILE_INPUT_STREAM
-G_IS_WINHTTP_FILE_INPUT_STREAM_CLASS
-G_IS_WINHTTP_FILE_OUTPUT_STREAM
-G_IS_WINHTTP_FILE_OUTPUT_STREAM_CLASS
-G_IS_WINHTTP_VFS
-G_IS_WINHTTP_VFS_CLASS
-G_LOCAL_FILE_IO_STREAM
-G_LOCAL_FILE_IO_STREAM_CLASS
-G_LOCAL_FILE_IO_STREAM_GET_CLASS
-G_SOCKET_INPUT_STREAM
-G_SOCKET_INPUT_STREAM_CLASS
-G_SOCKET_INPUT_STREAM_GET_CLASS
-G_SOCKET_OUTPUT_STREAM
-G_SOCKET_OUTPUT_STREAM_CLASS
-G_SOCKET_OUTPUT_STREAM_GET_CLASS
-G_TYPE_FEN_DIRECTORY_MONITOR
-G_TYPE_FEN_FILE_MONITOR
-G_TYPE_LOCAL_FILE_IO_STREAM
-G_TYPE_SOCKET_OUTPUT_STREAM
-G_TYPE_WIN32_DIRECTORY_MONITOR
-G_TYPE_WIN32_MOUNT
-G_TYPE_WIN32_VOLUME_MONITOR
-G_TYPE_WINHTTP_FILE
-G_TYPE_WINHTTP_FILE_INPUT_STREAM
-G_TYPE_WINHTTP_FILE_OUTPUT_STREAM
-G_TYPE_WINHTTP_VFS
-G_WIN32_DIRECTORY_MONITOR
-G_WIN32_DIRECTORY_MONITOR_CLASS
-G_WIN32_DIRECTORY_MONITOR_GET_CLASS
-G_WIN32_MOUNT
-G_WIN32_MOUNT_CLASS
-G_WIN32_VOLUME_MONITOR
-G_WIN32_VOLUME_MONITOR_CLASS
-G_WINHTTP_FILE
-G_WINHTTP_FILE_CLASS
-G_WINHTTP_FILE_GET_CLASS
-G_WINHTTP_FILE_INPUT_STREAM
-G_WINHTTP_FILE_INPUT_STREAM_CLASS
-G_WINHTTP_FILE_INPUT_STREAM_GET_CLASS
-G_WINHTTP_FILE_OUTPUT_STREAM
-G_WINHTTP_FILE_OUTPUT_STREAM_CLASS
-G_WINHTTP_FILE_OUTPUT_STREAM_GET_CLASS
-G_WINHTTP_VFS
-G_WINHTTP_VFS_CLASS
-G_WINHTTP_VFS_GET_CLASS
-g_win32_directory_monitor_get_type
-g_win32_directory_monitor_register
--- a/gio/gsettings.c
+++ b/gio/gsettings.c
@@ -30,6 +30,71 @@
 *
 * The #GSettings class provides a convenient API for storing and retrieving
 * application settings.
+ *
+ * When creating a GSettings instance, you have to specify a schema
+ * that describes the keys in your settings and their types and default
+ * values, as well as some other information.
+ *
+ * Normally, a schema has as fixed path that determines where the settings
+ * are stored in the conceptual global tree of settings. However, schemas
+ * can also be 'relocatable', i.e. not equipped with a fixed path. This is
+ * useful e.g. when the schema describes an 'account', and you want to be
+ * able to store a arbitrary number of accounts.
+ *
+ * Unlike other configuration systems (like GConf), GSettings does not
+ * restrict keys to basic types like strings and numbers. GSettings stores
+ * values as #GVariant, and allows any #GVariantType for keys.
+ *
+ * Similar to GConf, the default values in GSettings schemas can be
+ * localized, but the localized values are stored in gettext catalogs
+ * and looked up with the domain that is specified in the gettext-domain
+ * attribute of the <tag>schemalist</tag> or <tag>schema</tag> elements
+ * and the category that is specified in the l10n attribute of the
+ * <tag>key</tag> element.
+ *
+ * GSettings uses schemas in a compact binary form that is created
+ * by the gschema-compile utility. The input is a schema description in
+ * an XML format that can be described by the following DTD:
+ * |[<![CDATA[
+ * <!ELEMENT schemalist (schema*) >
+ * <!ATTLIST schemalist gettext-domain #IMPLIED >
+ *
+ * <!ELEMENT schema (key*) >
+ * <!ATTLIST schema id             CDATA #REQUIRED
+ *                  path           CDATA #IMPLIED
+ *                  gettext-domain CDATA #IMPLIED >
+ *
+ * <!ELEMENT key (default|summary?|description?|range?|choices?) >
+ * <!-- name can only contain lowercase letters, numbers and '-' -->
+ * <!-- type must be a GVariant type string -->
+ * <!ATTLIST key name CDATA #REQUIRED
+ *               type CDATA #REQUIRED >
+ *
+ * <!-- the default value is specified a a serialized GVariant,
+ *      i.e. you have to include the quotes when specifying a string -->
+ * <!ELEMENT default (#PCDATA) >
+ * <!-- the presence of the l10n attribute marks a default value for
+ *      translation, its value is the gettext category to use -->
+ * <!ATTLIST default l10n (ctype|numeric|time|collate|
+ *                         monetary|messages|all|paper|
+ *                         name|address|telephone|
+ *                         measurement|identification) #IMPLIED >
+ *
+ * <!ELEMENT summary (#PCDATA) >
+ * <!ELEMENT description (#PCDATA) >
+ *
+ * <!ELEMENT range (min,max)  >
+ * <!ELEMENT min (#PCDATA) >
+ * <!ELEMENT max (#PCDATA) >
+ *
+ * <!ELEMENT choices (choice+) >
+ * <!ELEMENT choice (alias?) >
+ * <!ATTLIST choice value CDATA #REQUIRED >
+ * <!ELEMENT choice (alias?) >
+ * <!ELEMENT alias EMPTY >
+ * <!ATTLIST alias value CDATA #REQUIRED >
+ * ]]>
+ * ]|
 */

 struct _GSettingsPrivate
--- a/gio/gsettingsschema.c
+++ b/gio/gsettingsschema.c
@@ -25,46 +25,6 @@

 #include "gvdb/gvdb-reader.h"

-/*
- * The #GSettingsSchema class provides schema information (i.e. types,
- * default values and descriptions) for keys in settings.
- *
- * Schema information is required to use #GSettings.
- *
- * The source format for GSettings schemas is an XML format that can
- * be described with the following DTD:
- * |[<![CDATA[
- * <!ELEMENT schemalist (schema*) >
- * <!ATTLIST schemalist gettext-domain #IMPLIED >
- *
- * <!ELEMENT schema (key*) >
- * <!ATTLIST schema id             #REQUIRED
- *                  path           #IMPLIED
- *                  gettext-domain #IMPLIED >
- *
- * <!ELEMENT key (default|summary?|description?|range?|choices?) >
- * <!ATTLIST key name #REQUIRED
- *               type #REQUIRED >
- *
- * <!ELEMENT default (#PCDATA) >
- * <!ATTLIST default l10n #IMPLIED >
- *
- * <!ELEMENT summary (#PCDATA) >
- * <!ELEMENT description (#PCDATA) >
- *
- * <!ELEMENT range (min,max)  >
- * <!ELEMENT min (#PCDATA) >
- * <!ELEMENT max (#PCDATA) >
- *
- * <!ELEMENT choices (choice+) >
- * <!ELEMENT choice (alias?) >
- * <!ATTLIST choice value #REQUIRED >
- * <!ELEMENT choice (alias?) >
- * <!ELEMENT alias EMPTY >
- * <!ATTLIST alias value #REQUIRED >
- * ]]>
- * ]|
- */

 G_DEFINE_TYPE (GSettingsSchema, g_settings_schema, G_TYPE_OBJECT)